/ Hex Artifact Content
Login

Artifact 9106176cf206c36f01f8b761ba62671818bbe6ff:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30  rs {H10010} <S60
0ac0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  100>.**.** The S
0ad0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0ae0: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0af0: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0b00: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0b10: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
0b20: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
0b30: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
0b40: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
0b50: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
0b60: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
0b70: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0b80: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0b90: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 57 2e 58  of the form "W.X
0ba0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22  .Y" or "W.X.Y.Z"
0bb0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65  ..** The W value
0bc0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f   is major versio
0bd0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20  n number and is 
0be0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0bf0: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61  te3..** The W va
0c00: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  lue only changes
0c10: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20   when backwards 
0c20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0c30: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77  .** broken and w
0c40: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65  e intend to neve
0c50: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64  r break backward
0c60: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0c70: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20  .** The X value 
0c80: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0c90: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0ca0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65  only changes whe
0cb0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d  n.** there are m
0cc0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68  ajor feature enh
0cd0: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61  ancements that a
0ce0: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70  re forwards comp
0cf0: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f  atible.** but no
0d00: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  t backwards comp
0d10: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59  atible..** The Y
0d20: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65   value is the re
0d30: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64  lease number and
0d40: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0d50: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0d60: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0d70: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76  back to 0 whenev
0d80: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e  er X is incremen
0d90: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61  ted..** The Z va
0da0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73  lue only appears
0db0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61   on branch relea
0dc0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ses..**.** The S
0dd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0de0: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67  MBER is an integ
0df0: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75  er that is compu
0e00: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77  ted as.** follow
0e10: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
0e20: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51  uote><pre>.** SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e40: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20  BER = W*1000000 
0e50: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20  + X*1000 + Y.** 
0e60: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
0e70: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  te>.**.** Since 
0e80: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
0e90: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
0ea0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
0eb0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
0ec0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
0ed0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
0ee0: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">fossil configu
0ef0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
0f00: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
0f10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55    The SQLITE_SOU
0f20: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20  RCE_ID.** macro 
0f30: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  is a string whic
0f40: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0f50: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0f60: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0f70: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0f80: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0f90: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ent system.  The
0fa0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
0fb0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64   the.** date and
0fc0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
0fd0: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
0fe0: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20  an SHA1 hash of 
0ff0: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f  the entire.** so
1000: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
1010: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1020: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1030: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1050: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
1060: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
1070: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1080: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1090: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
10a0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
10b0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d  H10011] [H10014]
10c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
10e0: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
10f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1100: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1110: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1130: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
1140: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
1150: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1160: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
1170: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
1180: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
1190: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
11a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
11b0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
11c0: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
11d0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
11e0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
11f0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1200: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1210: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1220: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 64 65  E_SOURCE_ID] #de
1230: 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61  fines in the hea
1240: 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 65 20  der,.** but are 
1250: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1260: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1270: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1280: 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75  r file.  Cautiou
1290: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
12a0: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
12b0: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
12c0: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
12d0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
12e0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
12f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1300: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1310: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1320: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1330: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
1340: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
1350: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
1360: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
1370: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
1380: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1390: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13a0: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
13b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
13c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
13d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
13e0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1410: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1420: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1430: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
1440: 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 5f 56  version,SQLITE_V
1450: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1460: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1470: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
1480: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1490: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14a0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e  urns the same in
14b0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a  formation as is.
14c0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ** in the sqlite
14d0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
14e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14f0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  e function is pr
1500: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73  ovided.** for us
1510: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1520: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1530: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69  y do not have di
1540: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
1550: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e  tring.** constan
1560: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1570: 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 74  L.  Similarly, t
1580: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1590: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  eid() function.*
15a0: 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  * returns the sa
15b0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
15c0: 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 51 4c  s is in the [SQL
15d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23  ITE_SOURCE_ID] #
15e0: 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  define of.** the
15f0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2a   header file..**
1600: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1610: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1620: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1630: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
1640: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1650: 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 32 5d  H10021] [H10022]
1660: 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 51 4c   [H10023].*/.SQL
1670: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
1680: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1690: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
16a0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16b0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
16c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
16d0: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
16e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
16f0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1700: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1710: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1720: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
1730: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
1740: 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31  e {H10100} <S601
1750: 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
1760: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1770: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1780: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1790: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17a0: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
17b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
17c0: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
17d0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
17e0: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
17f0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1800: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1810: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1820: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1830: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1840: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1850: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1860: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1870: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1880: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1890: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
18a0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
18b0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
18c0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
18d0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
18e0: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
18f0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1900: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1910: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1920: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1930: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1940: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1950: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1960: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1970: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1980: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
1990: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
19a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19b0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
19c0: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69   by an applicati
19d0: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
19e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
19f0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
1a00: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
1a10: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
1a20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
1a30: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
1a40: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
1a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1a60: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
1a70: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
1a80: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
1a90: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
1aa0: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
1ab0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1ac0: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
1ad0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1ae0: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
1af0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74  E_THREADSAFE=1 t
1b00: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
1b10: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1b20: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
1b30: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
1b40: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
1b50: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
1b60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
1b70: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
1b80: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
1b90: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
1ba0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1bb0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
1bc0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1bd0: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72  G_MUTEX].  The r
1be0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1bf0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
1c00: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64  ws.** only the d
1c10: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74  efault compile-t
1c20: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74  ime setting, not
1c30: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
1c40: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74  anges.** to that
1c50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
1c60: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
1c70: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
1c80: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
1c90: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1ca0: 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  n..**.** Require
1cb0: 6d 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20  ments: [H10101] 
1cc0: 5b 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20  [H10102].*/.int 
1cd0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1ce0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
1cf0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
1d00: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
1d10: 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c  andle {H12000} <
1d20: 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S40200>.** KEYWO
1d30: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
1d40: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
1d50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
1d70: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1d80: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
1d90: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
1da0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
1db0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
1dc0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
1dd0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
1de0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
1df0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
1e00: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
1e10: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
1e20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1e30: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1e40: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1e50: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1e60: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
1e70: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
1e80: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
1e90: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
1ea0: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
1eb0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
1ec0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
1ed0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
1ee0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
1ef0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1f00: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
1f10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1f20: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
1f30: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
1f40: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
1f50: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
1f60: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
1f70: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f80: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
1f90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
1fa0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
1fb0: 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31  s {H10200} <S101
1fc0: 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1fd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1fe0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
1ff0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2000: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2010: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2020: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2030: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2040: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2050: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2060: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2070: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2080: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2090: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
20a0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
20b0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
20c0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
20d0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
20e0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
20f0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2100: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2110: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2120: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2130: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2140: 5b 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32  [H10201] [H10202
2150: 5d 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ].*/.#ifdef SQLI
2160: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
2170: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
2180: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2190: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
21a0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
21b0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
21c0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
21d0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
21e0: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
21f0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
2200: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
2210: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2220: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2230: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
2240: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
2250: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
2260: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
2270: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2280: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
2290: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
22a0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
22b0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
22c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
22d0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
22e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
22f0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
2300: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
2310: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
2320: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
2330: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
2340: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
2350: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
2360: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
2370: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
2380: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
2390: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
23a0: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
23b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
23d0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
23e0: 31 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c  12010} <S30100><
23f0: 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
2400: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  is routine is th
2410: 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  e destructor for
2420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2430: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  bject..**.** App
2440: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2450: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2460: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2470: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2480: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2490: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
24a0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
24b0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
24c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
24d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
24e0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
24f0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2500: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  se the object..*
2510: 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  *.** If [sqlite3
2520: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76  _close()] is inv
2530: 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61  oked while a tra
2540: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nsaction is open
2550: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63  ,.** the transac
2560: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
2570: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2580: 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70  k..**.** The C p
2590: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
25a0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d  ite3_close(C)] m
25b0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
25c0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
25d0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
25e0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
25f0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
2600: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2610: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2620: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2630: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
2640: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
2650: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  sly closed..**.*
2660: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
2670: 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b 48 31 32  ** [H12011] [H12
2680: 30 31 32 5d 20 5b 48 31 32 30 31 33 5d 20 5b 48  012] [H12013] [H
2690: 31 32 30 31 34 5d 20 5b 48 31 32 30 31 35 5d 20  12014] [H12015] 
26a0: 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12019].*/.int 
26b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
26c0: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
26d0: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
26e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
26f0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
2700: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
2710: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
2720: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
2730: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
2740: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
2750: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2760: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2770: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2780: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2790: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
27a0: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
27b0: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
27c0: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48  ion Interface {H
27d0: 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12100} <S10000>.
27e0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27f0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
2800: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
2810: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
2820: 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  g one or more.**
2830: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2840: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
2850: 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66  o write a lot of
2860: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54   C code.  The UT
2870: 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53  F-8 encoded.** S
2880: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
2890: 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  e passed in as t
28a0: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
28b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
28c0: 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74  xec()..** The st
28d0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
28e0: 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e  luated one by on
28f0: 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61  e until either a
2900: 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e  n error or.** an
2910: 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e   interrupt is en
2920: 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e  countered, or un
2930: 74 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c  til they are all
2940: 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20   done.  The 3rd 
2950: 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2960: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c  an optional call
2970: 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76  back that is inv
2980: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
2990: 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75  ch row of any qu
29a0: 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70  ery.** results p
29b0: 72 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53  roduced by the S
29c0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
29d0: 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
29e0: 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a  r tells where.**
29f0: 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72   to write any er
2a00: 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a  ror messages..**
2a10: 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65  .** The error me
2a20: 73 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63  ssage passed bac
2a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
2a40: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68  h parameter is h
2a50: 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79  eld.** in memory
2a60: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2a70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2a80: 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d  ].  To avoid a m
2a90: 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74  emory leak,.** t
2aa0: 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69  he calling appli
2ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61  cation should ca
2ac0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
2ad0: 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72  ()] on any error
2ae0: 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75  .** message retu
2af0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
2b00: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77   5th parameter w
2b10: 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2b20: 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hed using.** the
2b30: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2b40: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2b50: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2b60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2b70: 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
2b80: 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72  pty string.** or
2b90: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
2ba0: 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73  ning only whites
2bb0: 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  pace and comment
2bc0: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a  s, then no SQL.*
2bd0: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  * statements are
2be0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
2bf0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  he database is n
2c00: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
2c10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2c20: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
2c30: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  s implemented in
2c40: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71   terms of.** [sq
2c50: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c60: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2c70: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2c80: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2c90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ca0: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64  exec() routine d
2cb0: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74  oes nothing to t
2cc0: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
2cd0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a   cannot be done.
2ce0: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
2cf0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2d00: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
2d10: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
2d20: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2d30: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2d40: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2d50: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
2d60: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
2d70: 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  n.** [database c
2d80: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
2d90: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63  * The database c
2da0: 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2db0: 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69  ot be closed whi
2dc0: 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  le.** [sqlite3_e
2dd0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  xec()] is runnin
2de0: 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  g..**.** The cal
2df0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
2e00: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
2e10: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
2e20: 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  e.** the memory 
2e30: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
2e40: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
2e50: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
2e60: 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f  ** message is no
2e70: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
2e80: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 73 74  **.** The SQL st
2e90: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20  atement text in 
2ea0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2eb0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
2ec0: 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 72 65  ec()].** must re
2ed0: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
2ee0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
2ef0: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
2f00: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2f10: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 31 30 31  ents:.** [H12101
2f20: 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48 31 32 31  ] [H12102] [H121
2f30: 30 34 5d 20 5b 48 31 32 31 30 35 5d 20 5b 48 31  04] [H12105] [H1
2f40: 32 31 30 37 5d 20 5b 48 31 32 31 31 30 5d 20 5b  2107] [H12110] [
2f50: 48 31 32 31 31 33 5d 20 5b 48 31 32 31 31 36 5d  H12113] [H12116]
2f60: 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20 5b 48 31  .** [H12119] [H1
2f70: 32 31 32 32 5d 20 5b 48 31 32 31 32 35 5d 20 5b  2122] [H12125] [
2f80: 48 31 32 31 33 31 5d 20 5b 48 31 32 31 33 34 5d  H12131] [H12134]
2f90: 20 5b 48 31 32 31 33 37 5d 20 5b 48 31 32 31 33   [H12137] [H1213
2fa0: 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8].*/.int sqlite
2fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
2fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
2fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
2ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
3000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
3010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
3030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
3040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
3050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
3070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
3080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
3090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
30a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
30c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
30d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
30e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
30f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
3110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
3120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  : Result Codes {
3140: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e  H10210} <S10700>
3150: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
3160: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
3170: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
3180: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
3190: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72  {result code} {r
31a0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
31b0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
31c0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
31d0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
31e0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
31f0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3200: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3210: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3220: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3230: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65  * New error code
3240: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
3250: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
3260: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
3270: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  ** See also: [SQ
3280: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3290: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
32a0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66  t codes].*/.#def
32b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
32c0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
32d0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
32e0: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
32f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
3300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3310: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
3320: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
3330: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
3340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3350: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
3360: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
3370: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
3380: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
3390: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
33a0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
33b0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
33c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
33d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
33e0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
33f0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
3400: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
3410: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3420: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
3430: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
3440: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
3450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
3460: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
3470: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
3480: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
3490: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
34a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
34b0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
34c0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
34d0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
34e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
34f0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
3500: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
3510: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
3520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3530: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
3540: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
3550: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
3560: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
3570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3580: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
3590: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
35a0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
35b0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
35c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
35d0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
35e0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
35f0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
3600: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
3610: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
3620: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20      12   /* NOT 
3630: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72  USED. Table or r
3640: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20  ecord not found 
3650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3660: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
3670: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
3680: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
3690: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
36a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36b0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
36c0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
36d0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
36e0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
36f0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
3700: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54  L    15   /* NOT
3710: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20   USED. Database 
3720: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
3730: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
3740: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
3750: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
3760: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
3770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
3780: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
3790: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
37a0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
37b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37c0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
37d0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
37e0: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
37f0: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
3800: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
3810: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
3820: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
3830: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
3840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3850: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
3860: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
3870: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
3880: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
3890: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
38a0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
38b0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
38c0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
38d0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
38e0: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
38f0: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
3900: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
3910: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
3920: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
3930: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
3940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3950: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
3960: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
3970: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
3980: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
3990: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
39a0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
39b0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
39c0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
39d0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
39e0: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
39f0: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
3a00: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
3a10: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
3a20: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3a30: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
3a40: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
3a50: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
3a60: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
3a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3a80: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
3a90: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
3aa0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
3ab0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
3ac0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
3ad0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
3ae0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
3af0: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
3b00: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0220} <S10700>.*
3b10: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
3b20: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
3b30: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  } {extended erro
3b40: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3b50: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
3b60: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78  result code} {ex
3b70: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3b80: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  des}.**.** In it
3b90: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
3ba0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
3bb0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
3bc0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e  urn one of 26 in
3bd0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
3be0: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
3bf0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
3c00: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
3c10: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
3c20: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
3c30: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
3c40: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
3c50: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
3c60: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
3c70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
3c80: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
3c90: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
3ca0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
3cb0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
3cc0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
3cd0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
3ce0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
3cf0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
3d00: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
3d10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
3d20: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
3d30: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
3d40: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
3d50: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
3d60: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3d70: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3d80: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
3d90: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
3da0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3db0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
3dc0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
3dd0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
3de0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a  odes()] API..**.
3df0: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
3e00: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
3e10: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
3e20: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
3e30: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
3e40: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
3e50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3e60: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
3e70: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
3e80: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
3e90: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
3ea0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
3eb0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
3ec0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
3ed0: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
3ee0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
3ef0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
3f00: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
3f10: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
3f20: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
3f30: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
3f40: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
3f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3f60: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
3f70: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3f80: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
3f90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3fa0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
3fb0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
3fc0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3ff0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4000: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
4010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4020: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
4030: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4040: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
4050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4060: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
4070: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4080: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
4090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
40a0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
40b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
40c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
40d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
40e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
40f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4100: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
4110: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4120: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
4130: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4140: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
4150: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4160: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
4170: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4180: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
4190: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
41a0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
41b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
41c0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
41d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
41e0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
41f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4200: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
4210: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
4220: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
4230: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4240: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
4250: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
4260: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
4270: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4280: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
4290: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
42a0: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
42b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
42c0: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
42d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
42e0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
42f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4300: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
4310: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
4320: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
4330: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4340: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
4350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
4360: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
4370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4380: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
4390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
43a0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
43b0: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
43c0: 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f 2a 0a 2a  | (1<<8) )../*.*
43d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
43e0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
43f0: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32  Operations {H102
4400: 33 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31  30} <H11120> <H1
4410: 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2700>.**.** Thes
4420: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
4430: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
4440: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
4450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4460: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
4470: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
4480: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
4490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
44a0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  e xOpen method o
44b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
44c0: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
44f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
4500: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
4510: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4530: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
4540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
4550: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
4560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
4590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
45a0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
45b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
45e0: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
45f0: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
4620: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
4630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
4660: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
4670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4690: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
46a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
46b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
46c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46d0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
46e0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
46f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
4720: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
4730: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4750: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
4760: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
4770: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
47a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
47b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
47e0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
47f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4810: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
4820: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
4830: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4840: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4850: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4860: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
4870: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
4880: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4890: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48b0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
48c0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
48d0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
48e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
4910: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
4920: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4930: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4940: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4950: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
4960: 74 65 72 69 73 74 69 63 73 20 7b 48 31 30 32 34  teristics {H1024
4970: 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a  0} <H11120>.**.*
4980: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
4990: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
49a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
49b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
49c0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
49d0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
49e0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
49f0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
4a00: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
4a10: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
4a20: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
4a30: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
4a40: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
4a50: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
4a60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4a70: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
4a80: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
4a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4aa0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
4ab0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
4ac0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
4ad0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
4ae0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4af0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
4b00: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
4b10: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
4b20: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
4b30: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
4b40: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
4b50: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
4b60: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
4b70: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
4b80: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
4b90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
4ba0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
4bb0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
4bc0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
4bd0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
4be0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
4bf0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
4c00: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
4c10: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
4c20: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
4c30: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
4c40: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
4c50: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
4c60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
4c70: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
4c80: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
4c90: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
4ca0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
4cb0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
4cc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4cd0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
4ce0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
4cf0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
4d00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
4d10: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
4d20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
4d30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4d40: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4d50: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
4d60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
4d70: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4d80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
4d90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
4da0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4db0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
4dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
4dd0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4de0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
4df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4e00: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
4e10: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
4e20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
4e30: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
4e40: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
4e60: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
4e70: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
4e80: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
4e90: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
4ea0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
4eb0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
4ec0: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
4ed0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
4ee0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
4ef0: 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30  g Levels {H10250
4f00: 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33  } <H11120> <H113
4f10: 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  10>.**.** SQLite
4f20: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
4f30: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
4f40: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
4f50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
4f60: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
4f70: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
4f80: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
4f90: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
4fa0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4fb0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
4fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4fd0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
4fe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4ff0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
5000: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
5010: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5020: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
5030: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
5040: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5060: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
5070: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5080: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
5090: 20 54 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30   Type Flags {H10
50a0: 32 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a  260} <H11120>.**
50b0: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
50c0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
50d0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
50e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
50f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5100: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5110: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5120: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5130: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5140: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5150: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5160: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5170: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5180: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5190: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
51a0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
51b0: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
51c0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
51d0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
51e0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
51f0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5200: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
5210: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
5220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5230: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
5240: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5250: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
5260: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5270: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5290: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
52a0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
52b0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
52c0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
52d0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
52e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
52f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5380: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
5390: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
53a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
53b0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
53c0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
53d0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
53e0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
53f0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
5400: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
5410: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
5420: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
5430: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
5440: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
5450: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
5460: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
5470: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
5480: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
5490: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
54a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
54b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
54c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
54d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
54e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
54f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
5500: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5510: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5520: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
5530: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
5540: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
5550: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
5560: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5570: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
5580: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
5590: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
55a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
55b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
55c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
55d0: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31  hods Object {H11
55e0: 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  120} <S20110>.**
55f0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
5600: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
5610: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
5620: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
5630: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
5640: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
5650: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
5660: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
5670: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5680: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
5690: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
56a0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
56b0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
56c0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
56d0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
56e0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
56f0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
5700: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
5710: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
5720: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
5730: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
5740: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
5750: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73  e xOpen method s
5760: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
5770: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
5780: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
5790: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
57a0: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
57b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
57c0: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
57d0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
57e0: 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72  n if the xOpen r
57f0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
5800: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
5810: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
5820: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
5830: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
5840: 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a   failed xOpen.**
5850: 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65   is for the xOpe
5860: 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  n to set the sql
5870: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
5880: 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55  ds element to NU
5890: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
58a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
58b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
58c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
58d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
58e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
58f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5900: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5910: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5920: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5930: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5940: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
5950: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
5960: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
5970: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5980: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
5990: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
59a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
59b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
59c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
59d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
59e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
59f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5a00: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5a10: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5a20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5a30: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5a40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5a50: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5a60: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5a70: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5a90: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
5aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5ab0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5ac0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5ad0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5ae0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5af0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5b00: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5b10: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5b20: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5b30: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5b40: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
5b50: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
5b60: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
5b70: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
5b80: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
5b90: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
5ba0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5bb0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5bc0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5bd0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5be0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5bf0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5c00: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5c10: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5c20: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5c30: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5c40: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
5c50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
5c60: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
5c70: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
5c80: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
5c90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
5ca0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5cb0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5cc0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5cd0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5ce0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5cf0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5d00: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5d10: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5d20: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5d30: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5d40: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
5d50: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
5d60: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
5d70: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
5d80: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
5d90: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
5da0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5db0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5dc0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5dd0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5de0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5df0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5e00: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5e10: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5e20: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5e30: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5e40: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
5e50: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
5e60: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
5e70: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
5e80: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
5e90: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
5ea0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5eb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5ec0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5ed0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5ee0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5ef0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5f00: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5f10: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5f20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5f30: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5f40: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
5f50: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
5f60: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
5f70: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
5f80: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
5f90: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
5fa0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5fb0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5fc0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5fd0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5fe0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5ff0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
6000: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
6010: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
6020: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
6030: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6040: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6050: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
6060: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
6070: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
6080: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
6090: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
60a0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
60b0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
60c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
60d0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
60e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
60f0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
6100: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6110: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
6120: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6130: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6140: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6150: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6170: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
6180: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6190: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
61a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
61b0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
61c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
61d0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
61e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
61f0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
6200: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6210: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
6220: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
6230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6240: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6250: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6260: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6270: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6280: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6290: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
62a0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
62b0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
62c0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
62d0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
62e0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
62f0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6300: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6310: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6320: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6340: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6350: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6360: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6370: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6380: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6390: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
63a0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
63b0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
63c0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
63d0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
63e0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
63f0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6400: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6410: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6420: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6430: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6440: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6450: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6460: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
6470: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
6480: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
6490: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
64a0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
64b0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
64c0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
64d0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
64e0: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
64f0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
6500: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
6510: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
6520: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
6530: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
6540: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
6550: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
6560: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
6570: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
6580: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6590: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
65a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65b0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
65c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
65d0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
65e0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
65f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6600: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
6610: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
6620: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6630: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
6640: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
6650: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6660: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
6670: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6680: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6690: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
66a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
66b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
66c0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
66d0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
66e0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
66f0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6700: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6710: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6720: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6730: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6740: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6750: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
6760: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6770: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
6780: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
6790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
67a0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
67b0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
67c0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
67d0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
67e0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
67f0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6800: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6810: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6820: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6840: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
6850: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
6860: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
6870: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
6880: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
6890: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
68a0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
68b0: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
68c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
68d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
68e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
68f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6900: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6910: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6920: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6930: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6940: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
6950: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
6960: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
6970: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
6980: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
6990: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
69a0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
69b0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
69c0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
69d0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
69e0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
69f0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6a10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6a20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6a30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6a40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
6a50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
6a60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6a70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
6a80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
6a90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
6aa0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6ab0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6ac0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6ad0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6ae0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6af0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6b00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6b20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6b30: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
6b50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
6b60: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6b70: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
6b80: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
6b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
6ba0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6bb0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6bc0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6bd0: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6be0: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6bf0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6c00: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6c10: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6c20: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6c30: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6c40: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
6c50: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
6c60: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
6c70: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
6c80: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
6c90: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
6ca0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6cb0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6cc0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6cd0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6ce0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6cf0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6d00: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6d10: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6d20: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6d30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6d40: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
6d50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6d60: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
6d70: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
6d80: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
6d90: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
6da0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6db0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6dc0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6dd0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6de0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6df0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6e00: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6e10: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6e20: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6e30: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6e40: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
6e50: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
6e60: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
6e70: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
6e80: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
6e90: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
6ea0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6eb0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6ec0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6ed0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6ee0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6ef0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6f00: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6f10: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6f20: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6f30: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6f40: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
6f50: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
6f60: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
6f70: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
6f80: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
6f90: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
6fa0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6fb0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6fc0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6fd0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6fe0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6ff0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7000: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7010: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7020: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7030: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7040: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7050: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7060: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7070: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7080: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7090: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
70a0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
70b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
70c0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
70d0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
70e0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
70f0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7100: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7110: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7120: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7130: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7140: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7150: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7160: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7170: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7180: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7190: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
71a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
71b0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
71c0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
71d0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
71e0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
71f0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7200: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7210: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7220: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7230: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7240: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7250: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7260: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7270: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7280: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7290: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
72a0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
72b0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
72c0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
72d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
72e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
72f0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7300: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7310: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7320: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7330: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7340: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7350: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7360: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7370: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7380: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7390: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
73a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
73b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
73c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
73d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
73e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
73f0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7400: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7410: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7420: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7430: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7440: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7450: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7460: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7470: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7480: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7490: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
74a0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
74b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
74c0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
74d0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
74e0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
74f0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
7500: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
7510: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
7520: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
7530: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
7540: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
7550: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
7560: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
7570: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
7580: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
7590: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
75a0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
75b0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
75c0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
75d0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
75e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
75f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
7600: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7610: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
7620: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
7630: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
7640: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7650: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
7660: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
7670: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7680: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
7690: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
76a0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
76b0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
76c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
76d0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
76e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
76f0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7700: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7710: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7720: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7730: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7740: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
7750: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
7760: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
7770: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
7780: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7790: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
77a0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
77b0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
77c0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
77d0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
77e0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
77f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7800: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7810: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7820: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7830: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7840: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7850: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
7860: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7870: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
7880: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7890: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
78a0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
78b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
78c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
78d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
78e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
78f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7900: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7910: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7920: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7930: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7940: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
7950: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
7960: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
7970: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
7980: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
7990: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
79a0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
79b0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
79c0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
79d0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
79e0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
79f0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7a00: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7a10: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7a20: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7a30: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7a40: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
7a50: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
7a60: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
7a70: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
7a80: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
7a90: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
7aa0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7ab0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7ac0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7ad0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7ae0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7af0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7b00: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7b10: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7b20: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7b30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7b40: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
7b50: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
7b60: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7b70: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7b80: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7b90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7ba0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7bc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7bd0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7be0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7bf0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7c00: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7c10: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7c20: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7c30: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7c40: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
7c50: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
7c60: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
7c70: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
7c80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7c90: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
7ca0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
7cb0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
7cc0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
7cd0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
7ce0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
7cf0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
7d00: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
7d10: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
7d20: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
7d30: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
7d40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
7d50: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
7d60: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
7d70: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
7d80: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
7d90: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
7da0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
7db0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
7dc0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
7dd0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
7de0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
7df0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
7e00: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
7e10: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
7e20: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
7e30: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
7e40: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
7e50: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
7e60: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
7e70: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
7e80: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
7e90: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
7ea0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
7eb0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
7ec0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
7ed0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
7ee0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
7ef0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
7f00: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
7f10: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
7f20: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
7f30: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
7f40: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
7f50: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
7f60: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
7f70: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7f80: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
7f90: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
7fa0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7fb0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
7fc0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
7fd0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
7fe0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
7ff0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8000: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8010: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8020: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8030: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8040: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8050: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8060: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8070: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8080: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8090: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
80a0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
80b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
80c0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
80d0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
80e0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
80f0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8100: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8110: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8120: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8130: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8140: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8150: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8160: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8170: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8180: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8190: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
81a0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
81b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
81c0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
81d0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
81e0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
81f0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8200: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8210: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8220: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8230: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8240: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8250: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8260: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8270: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8280: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8290: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
82a0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
82b0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
82c0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
82d0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
82e0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
82f0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8310: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8320: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8330: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8340: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8350: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8360: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8370: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8380: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8390: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
83a0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
83b0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
83c0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
83d0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
83e0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
83f0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8400: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8410: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8420: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8430: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8440: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8450: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8460: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8470: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8480: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8490: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
84a0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
84b0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
84c0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
84d0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
84e0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
84f0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8500: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8510: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8520: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8530: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8540: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8550: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8560: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8570: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8580: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
8590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
85a0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
85b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
85c0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
85d0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
85e0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
85f0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
8600: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
8610: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
8620: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
8640: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
8650: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
8660: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
8670: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
8680: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
8690: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
86a0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
86b0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
86c0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
86d0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
86e0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
86f0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
8700: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
8710: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
8720: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
8730: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
8740: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
8750: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8760: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
8770: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
8780: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
8790: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
87a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
87b0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
87c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
87d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
87e0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
87f0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
8800: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8810: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
8820: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8830: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
8840: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
8850: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
8860: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
8870: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
8880: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
8890: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
88a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
88b0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
88c0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
88d0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
88e0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
88f0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
8900: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
8910: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
8920: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
8930: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
8940: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
8950: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
8960: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
8970: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
8980: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8990: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
89a0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
89b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
89c0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
89d0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
89e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
89f0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
8a00: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
8a10: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
8a20: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
8a30: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
8a40: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
8a50: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
8a60: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
8a70: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
8a80: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
8a90: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
8aa0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
8ab0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
8ac0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
8ad0: 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39  FS method {H1119
8ae0: 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a  0} <H11140>.**.*
8af0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8b00: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
8b10: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
8b20: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
8b30: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
8b40: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
8b50: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
8b60: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65  . {END}  They de
8b70: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
8b80: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
8b90: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
8ba0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
8bb0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
8bc0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
8bd0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
8be0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
8bf0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
8c00: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
8c10: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8c20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8c30: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
8c40: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
8c50: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
8c60: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8c70: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
8c80: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
8c90: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
8ca0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
8cb0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
8cc0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
8cd0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
8ce0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8cf0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
8d00: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8d10: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
8d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
8d30: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
8d40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8d50: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
8d60: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
8d70: 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e  H10130} <S20000>
8d80: 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
8d90: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
8da0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
8db0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
8dc0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
8dd0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
8de0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
8df0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
8e00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
8e10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
8e20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
8e30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
8e40: 54 68 69 73 20 72 6f 75 74 69 6e 65 73 20 61 72  This routines ar
8e50: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
8e60: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
8e70: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
8e80: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
8e90: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
8ea0: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
8eb0: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
8ec0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
8ed0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
8ee0: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
8ef0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
8f00: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
8f10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
8f20: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
8f30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
8f40: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
8f50: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
8f60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8f70: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
8f80: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
8f90: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
8fa0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
8fb0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
8fc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8fd0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
8fe0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
8ff0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9000: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e  down().  Only an
9010: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9020: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9030: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9040: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9050: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9060: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9070: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  less no-ops..**.
9080: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
9090: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
90a0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
90b0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
90c0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
90d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
90e0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
90f0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
9100: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e  nitialize().  On
9110: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
9120: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
9130: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
9140: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
9150: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
9160: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
9170: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
9180: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
9190: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  less no-ops..**.
91a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
91b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
91c0: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
91d0: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
91e0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
91f0: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
9200: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
9210: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
9220: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
9230: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
9240: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
9250: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
9260: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
9270: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
9280: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
9290: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
92a0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
92b0: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
92c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
92d0: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
92e0: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73   other things, s
92f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9300: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
9310: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9320: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9330: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
9340: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
9350: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9360: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9370: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9380: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9390: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
93a0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
93b0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
93c0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
93d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
93e0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
93f0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
9400: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
9410: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
9420: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
9430: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
9440: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
9450: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
9460: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
9470: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
9480: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9490: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
94a0: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
94b0: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
94c0: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
94d0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
94e0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
94f0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
9500: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
9510: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
9520: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9530: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
9540: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9550: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
9560: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9570: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9580: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9590: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
95a0: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
95b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
95c0: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
95d0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
95e0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
95f0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
9600: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
9610: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
9620: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
9630: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
9640: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
9650: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
9660: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
9670: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
9680: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
9690: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
96a0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
96b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
96c0: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
96d0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
96e0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
96f0: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
9700: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
9710: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
9720: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
9730: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
9740: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
9750: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
9760: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
9770: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9780: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9790: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
97a0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
97b0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
97c0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
97d0: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
97e0: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
97f0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
9800: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
9810: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
9820: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
9830: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
9840: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
9850: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
9860: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
9870: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9880: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
9890: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
98a0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
98b0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
98c0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
98d0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
98e0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
98f0: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
9900: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
9910: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
9920: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
9930: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
9940: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
9950: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
9960: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
9970: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
9980: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
9990: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
99a0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
99b0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
99c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
99d0: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
99e0: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
99f0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
9a00: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
9a10: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
9a20: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
9a30: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
9a40: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
9a50: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
9a60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
9a70: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
9a80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9a90: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
9aa0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
9ab0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
9ac0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9ad0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
9ae0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
9af0: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
9b00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
9b10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9b20: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
9b30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
9b40: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
9b50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9b60: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
9b70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
9b80: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
9b90: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9ba0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
9bb0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
9bc0: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
9bd0: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
9be0: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
9bf0: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
9c00: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
9c10: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
9c20: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
9c30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
9c40: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
9c50: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
9c60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9c70: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
9c80: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
9c90: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
9ca0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9cb0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9cc0: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
9cd0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
9ce0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9cf0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9d00: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
9d10: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
9d20: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
9d30: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
9d40: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
9d50: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
9d60: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
9d70: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
9d80: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
9d90: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9da0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9db0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9dc0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9dd0: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9de0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9df0: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9e00: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9e10: 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14100} <S20000>
9e20: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
9e30: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
9e40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9e50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9e60: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
9e70: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
9e80: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
9e90: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9ea0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9eb0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9ec0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9ed0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9ee0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9ef0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9f00: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
9f10: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
9f20: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
9f30: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
9f40: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
9f50: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
9f60: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
9f70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
9f80: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
9f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9fa0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9fb0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9fc0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9fd0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9fe0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9ff0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
a000: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
a010: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
a020: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
a030: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a040: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
a050: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
a060: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
a070: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
a080: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
a090: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
a0a0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
a0b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a0c0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
a0d0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
a0e0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
a0f0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
a100: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
a110: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
a120: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
a130: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
a140: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
a150: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
a160: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a170: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
a180: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
a190: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a1a0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
a1b0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
a1c0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
a1d0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a1e0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
a1f0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
a200: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
a210: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
a220: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
a230: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
a240: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
a250: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
a260: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a270: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a280: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
a290: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a2a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
a2b0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a2c0: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
a2d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
a2e0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a2f0: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  ]..** If the opt
a300: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a310: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a320: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a330: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a340: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a350: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a360: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
a370: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
a380: 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31  * [H14103] [H141
a390: 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31  06] [H14120] [H1
a3a0: 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b  4123] [H14126] [
a3b0: 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d  H14129] [H14132]
a3c0: 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31   [H14135].** [H1
a3d0: 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b  4138] [H14141] [
a3e0: 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d  H14144] [H14147]
a3f0: 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35   [H14150] [H1415
a400: 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34  3] [H14156] [H14
a410: 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d  159].** [H14162]
a420: 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36   [H14165] [H1416
a430: 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  8].*/.SQLITE_EXP
a440: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
a450: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
a460: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
a470: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
a480: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
a490: 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30  ections  {H14200
a4a0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
a4b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
a4c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
a4d0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a4e0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a4f0: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
a500: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
a510: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a520: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
a530: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
a540: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a550: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
a560: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
a570: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
a580: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
a590: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
a5a0: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
a5b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
a5c0: 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
a5d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
a5e0: 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20  erface can only 
a5f0: 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74  be used immediat
a600: 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65  ely after.** the
a610: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a620: 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20  tion is created 
a630: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
a640: 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  pen()],.** [sqli
a650: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
a660: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
a670: 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  v2()].  .**.** T
a680: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
a690: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
a6a0: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
a6b0: 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66    is the.** conf
a6c0: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d  iguration verb -
a6d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
a6e0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
a6f0: 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f  what.** aspect o
a700: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
a710: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
a720: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
a730: 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f  .** The only cho
a740: 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c  ice for this val
a750: 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42  ue is [SQLITE_DB
a760: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
a770: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
a780: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
a790: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
a7a0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
a7b0: 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ite..** Addition
a7c0: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70  al arguments dep
a7d0: 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e  end on the verb.
a7e0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
a7f0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d  nts:.** [H14203]
a800: 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30   [H14206] [H1420
a810: 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34  9] [H14212] [H14
a820: 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  215].*/.SQLITE_E
a830: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
a840: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a850: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
a860: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
a870: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
a880: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
a890: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
a8a0: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
a8b0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
a8c0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
a8d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
a8e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
a8f0: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
a900: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
a910: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a920: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
a930: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
a940: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
a950: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
a960: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
a970: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
a980: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a990: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
a9a0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
a9b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a9c0: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
a9d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a9e0: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
a9f0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
aa00: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
aa10: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
aa20: 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
aa30: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
aa40: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
aa50: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
aa60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
aa70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
aa80: 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
aa90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
aaa0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
aab0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
aac0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
aad0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
aae0: 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
aaf0: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
ab00: 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
ab10: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
ab20: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
ab30: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
ab40: 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
ab50: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
ab60: 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
ab70: 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
ab80: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
ab90: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
aba0: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
abb0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
abc0: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
abd0: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
abe0: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
abf0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
ac00: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
ac10: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
ac20: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
ac30: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
ac40: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
ac50: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
ac60: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
ac70: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
ac80: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
ac90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
aca0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
acb0: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
acc0: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
acd0: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
ace0: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
acf0: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
ad00: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
ad10: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
ad20: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
ad30: 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  c and xFree meth
ad40: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
ad50: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
ad60: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
ad70: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
ad80: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
ad90: 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61  ary..** The xRea
ada0: 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74  lloc method must
adb0: 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c   work like reall
adc0: 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74  oc() from the st
add0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
ade0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63  .** with the exc
adf0: 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74  eption that if t
ae00: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ae10: 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69  nt to xRealloc i
ae20: 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c  s zero,.** xReal
ae30: 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f  loc must be a no
ae40: 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f  -op - it must no
ae50: 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c  t perform any al
ae60: 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64  location or.** d
ae70: 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 53 51  eallocation.  SQ
ae80: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 64 73  Lite guaranteeds
ae90: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
aea0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
aeb0: 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
aec0: 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
aed0: 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
aee0: 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
aef0: 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61  .** And so in ca
af00: 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64  ses where xRound
af10: 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  up always return
af20: 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
af30: 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ber,.** xRealloc
af40: 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61   can perform exa
af50: 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e  ctly as the stan
af60: 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61  dard library rea
af70: 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74  lloc() and.** st
af80: 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69  ill be in compli
af90: 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73  ance with this s
afa0: 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
afb0: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
afc0: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
afd0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
afe0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
aff0: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
b000: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
b010: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
b020: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
b030: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
b040: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
b050: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
b060: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
b070: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
b080: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
b090: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
b0a0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
b0b0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
b0c0: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
b0d0: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
b0e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
b0f0: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
b100: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
b110: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
b120: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b130: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
b140: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
b150: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
b160: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
b170: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
b180: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
b190: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
b1a0: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
b1b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
b1c0: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
b1d0: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
b1e0: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
b1f0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
b200: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
b210: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
b220: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
b230: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
b240: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
b250: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b260: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
b270: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
b280: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
b290: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b2a0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
b2b0: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
b2c0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
b2d0: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
b2e0: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
b2f0: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
b300: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
b310: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b320: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
b330: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
b340: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b350: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
b360: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
b370: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
b380: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
b390: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
b3a0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
b3b0: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
b3c0: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
b3d0: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
b3e0: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
b3f0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
b400: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
b410: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
b420: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
b430: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
b440: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
b450: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
b460: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
b470: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b480: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
b490: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
b4a0: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
b4b0: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
b4c0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
b4d0: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
b4e0: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
b4f0: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
b500: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
b510: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
b520: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
b530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
b540: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
b550: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b560: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
b570: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
b580: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
b590: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
b5a0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
b5b0: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
b5c0: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
b5d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b5e0: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
b5f0: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
b600: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
b610: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
b620: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
b630: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
b640: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
b650: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
b660: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
b670: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
b680: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
b690: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
b6a0: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
b6b0: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
b6c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
b6d0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b6e0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
b6f0: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
b700: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b710: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
b720: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
b730: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
b740: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
b750: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
b760: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
b770: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
b780: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
b790: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
b7a0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
b7b0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
b7c0: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
b7d0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
b7e0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
b7f0: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
b800: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
b810: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
b820: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
b830: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
b840: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
b850: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
b860: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
b870: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
b880: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
b890: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
b8a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b8b0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
b8c0: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
b8d0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
b8e0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
b8f0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
b900: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
b910: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
b920: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
b930: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
b940: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
b950: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
b960: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
b970: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30   {H10160} <S2000
b980: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
b990: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
b9a0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
b9b0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
b9c0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
b9d0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
b9e0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
b9f0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
ba00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
ba10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
ba20: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
ba30: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
ba40: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
ba50: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ba60: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
ba70: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
ba80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ba90: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
baa0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
bab0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
bac0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
bad0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
bae0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
baf0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
bb00: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
bb10: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
bb20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bb30: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
bb40: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
bb50: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
bb60: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
bb70: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
bb80: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
bb90: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
bba0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
bbb0: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
bbc0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
bbd0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
bbe0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
bbf0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
bc00: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
bc10: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
bc20: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
bc30: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
bc40: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
bc50: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
bc60: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
bc70: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a  le thread.</dd>.
bc80: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
bc90: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
bca0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
bcb0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
bcc0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
bcd0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
bce0: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
bcf0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
bd00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bd10: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
bd20: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
bd30: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
bd40: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
bd50: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
bd60: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
bd70: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bd80: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
bd90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
bda0: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
bdb0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
bdc0: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
bdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
bde0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
bdf0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
be00: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
be10: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
be20: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
be30: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
be40: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
be50: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
be60: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74  ame time.  See t
be70: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
be80: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61  de].** documenta
be90: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
bea0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
beb0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bec0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
bed0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
bee0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
bef0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
bf00: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
bf10: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
bf20: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
bf30: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
bf40: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
bf50: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
bf60: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
bf70: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
bf80: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
bf90: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
bfa0: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
bfb0: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
bfc0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
bfd0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
bfe0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
bff0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
c000: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
c010: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
c020: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c030: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
c040: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
c050: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
c060: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
c070: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
c080: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
c090: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
c0a0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
c0b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
c0c0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
c0d0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
c0e0: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65  time..** See the
c0f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
c100: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
c110: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
c120: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
c130: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c140: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
c150: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c160: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
c170: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c180: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
c190: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c1a0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c1b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c1c0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
c1d0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
c1e0: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
c1f0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
c200: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c210: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c220: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
c230: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
c240: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c250: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
c260: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
c270: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c280: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
c290: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c2a0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c2b0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c2c0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c2d0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c2e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c2f0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
c300: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
c310: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c320: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
c330: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c340: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
c350: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
c360: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c370: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
c380: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
c390: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
c3a0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
c3b0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c3c0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c3d0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
c3e0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
c3f0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
c400: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
c410: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
c420: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
c430: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c440: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
c450: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c460: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
c470: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
c480: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
c490: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
c4a0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
c4b0: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
c4c0: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
c4d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4e0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
c4f0: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  s. When disabled
c500: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
c510: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c520: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e  s become .** non
c530: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
c540: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
c550: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
c560: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
c570: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c580: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c590: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c5a0: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
c5b0: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
c5c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
c5d0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  ()].**   </ul>.*
c5e0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
c5f0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c600: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
c610: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c620: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c630: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c640: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c650: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
c660: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
c670: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c680: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
c690: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
c6a0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
c6b0: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
c6c0: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
c6d0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
c6e0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
c6f0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
c700: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
c710: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
c720: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
c730: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
c740: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
c750: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
c760: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
c770: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
c780: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
c790: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
c7a0: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
c7b0: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
c7c0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
c7d0: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
c7e0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
c7f0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c800: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74  should pointer t
c810: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
c820: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
c830: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
c840: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
c850: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
c860: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
c870: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
c880: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
c890: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
c8a0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
c8b0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
c8c0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
c8d0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
c8e0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
c8f0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
c900: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
c910: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
c920: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
c930: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
c940: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
c950: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
c960: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
c970: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
c980: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
c990: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
c9a0: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
c9b0: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
c9c0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
c9d0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
c9e0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
c9f0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
ca00: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
ca10: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
ca20: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
ca30: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
ca40: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
ca50: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ca60: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
ca70: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
ca80: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
ca90: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
caa0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
cab0: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
cac0: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
cad0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
cae0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
caf0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
cb00: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
cb10: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
cb20: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
cb30: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
cb40: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
cb50: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
cb60: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
cb70: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
cb80: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
cb90: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
cba0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
cbb0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
cbc0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
cbd0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
cbe0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
cbf0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
cc00: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
cc10: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
cc20: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
cc30: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
cc40: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
cc50: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
cc60: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
cc70: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
cc80: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
cc90: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
cca0: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
ccb0: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
ccc0: 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 61 64  .  The page head
ccd0: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
cce0: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
ccf0: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
cd00: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
cd10: 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73    It is harmless
cd20: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
cd30: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
cd40: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
cd50: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
cd60: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
cd70: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
cd80: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
cd90: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
cda0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
cdb0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
cdc0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
cdd0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
cde0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
cdf0: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
ce00: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
ce10: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
ce20: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
ce30: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
ce40: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
ce50: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
ce60: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
ce70: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
ce80: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
ce90: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
cea0: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
ceb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cec0: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
ced0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
cee0: 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ce..** The imple
cef0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
cf00: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
cf10: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
cf20: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
cf30: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
cf40: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
cf50: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
cf60: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
cf70: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
cf80: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
cf90: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
cfa0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
cfb0: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
cfc0: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
cfd0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cfe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
cff0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d000: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
d010: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
d020: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
d030: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
d040: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
d050: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
d060: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
d070: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
d080: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
d090: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
d0a0: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
d0b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
d0c0: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
d0d0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
d0e0: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
d0f0: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
d100: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
d110: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
d120: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
d130: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
d140: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
d150: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49  ation size..** I
d160: 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
d170: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
d180: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
d190: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
d1a0: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
d1b0: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
d1c0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
d1d0: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
d1e0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
d1f0: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
d200: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
d210: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
d220: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
d230: 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72   If the.** memor
d240: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
d250: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
d260: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
d270: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
d280: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
d290: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
d2a0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
d2b0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
d2c0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
d2d0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
d2e0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
d2f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d300: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
d310: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
d320: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
d330: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
d340: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
d350: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
d360: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
d370: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
d380: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
d390: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d3a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d3b0: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d3c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d3d0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d3e0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d3f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d400: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d410: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d420: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d430: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d440: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d450: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d460: 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
d470: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
d480: 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
d490: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
d4a0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
d4b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d4c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d4d0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
d4e0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d4f0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d500: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d510: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d520: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d530: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d540: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d550: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
d560: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
d570: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
d580: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
d590: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
d5a0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
d5b0: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
d5c0: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
d5d0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
d5e0: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
d5f0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
d600: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
d610: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
d620: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
d630: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
d640: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
d650: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
d660: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
d670: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d680: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
d690: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d6a0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
d6b0: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
d6c0: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
d6d0: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
d6e0: 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  location lookasi
d6f0: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
d700: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
d710: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
d720: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
d730: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
d740: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d750: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
d760: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
d770: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
d780: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d790: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  .  This option s
d7a0: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
d7b0: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
d7c0: 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 20 5b  ide size.  The [
d7d0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
d7e0: 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
d7f0: 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
d800: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
d810: 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
d820: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
d830: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
d840: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
d850: 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 64 3e  onnections.</dd>
d860: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d870: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
d880: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d890: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d8a0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d8b0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d8c0: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
d8d0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
d8e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ods] object.  Th
d8f0: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
d900: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
d910: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
d920: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
d930: 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c  ementation.  SQL
d940: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
d950: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
d960: 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
d970: 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
d980: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
d990: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d9a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d9b0: 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  TPCACHE</dt>.** 
d9c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
d9d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d9e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d9f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
da00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
da10: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
da20: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
da30: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
da40: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
da50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
da60: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
da70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
da80: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
da90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
daa0: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
dab0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
dac0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
dad0: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
dae0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
daf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
db00: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
db10: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
db20: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
db30: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
db40: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
db50: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
db60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
db70: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
db80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
db90: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
dba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
dbb0: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
dbc0: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
dbd0: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
dbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dbf0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
dc00: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
dc10: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
dc20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc30: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
dc40: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
dc50: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
dc60: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
dc70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
dc80: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
dc90: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
dca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
dcb0: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
dcc0: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
dcd0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
dce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcf0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
dd00: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
dd10: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
dd20: 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
dd30: 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
dd40: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
dd50: 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
dd60: 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
dd70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
dd80: 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
dd90: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
dda0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ddb0: 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
ddc0: 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
ddd0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
dde0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ddf0: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
de00: 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
de10: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
de20: 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ds* */../*.** CA
de30: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
de40: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
de50: 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10170} <S20000>.
de60: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
de70: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
de80: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
de90: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
dea0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
deb0: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
dec0: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
ded0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
dee0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
def0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
df00: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
df10: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
df20: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
df30: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
df40: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
df50: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
df60: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
df70: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
df80: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
df90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
dfa0: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
dfb0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
dfc0: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
dfd0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
dfe0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
dff0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
e000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
e010: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
e020: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
e030: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
e040: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
e050: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
e060: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
e070: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
e080: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
e090: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
e0a0: 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
e0b0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
e0c0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
e0d0: 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
e0e0: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
e0f0: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
e100: 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
e110: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
e120: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
e130: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
e140: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e150: 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
e160: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
e170: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
e180: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
e190: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
e1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
e1b0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
e1c0: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
e1d0: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65  e memory..** The
e1e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e1f0: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
e200: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
e210: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
e220: 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
e230: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
e240: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
e250: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63  loc()].  The sec
e260: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
e270: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
e280: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
e290: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
e2a0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
e2b0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e2c0: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
e2d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
e2e0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
e2f0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e300: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
e310: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
e320: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
e330: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
e340: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
e350: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
e360: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e370: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
e380: 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 6f 6e  y.  If the secon
e390: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f  d argument is no
e3a0: 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c 65 20  t.** a multiple 
e3b0: 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
e3c0: 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 20 64  rnally rounded d
e3d0: 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
e3e0: 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69  smaller.** multi
e3f0: 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 61  ple of 8.  See a
e400: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  lso: [SQLITE_CON
e410: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f  FIG_LOOKASIDE]</
e420: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
e430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e440: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
e450: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
e460: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
e470: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
e480: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
e490: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
e4a0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
e4b0: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
e4c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e4d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e4e0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
e4f0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
e500: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
e510: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
e520: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
e530: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
e540: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
e550: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
e560: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
e570: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
e580: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
e590: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
e5a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
e5b0: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
e5c0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e5d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e5e0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
e5f0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
e600: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
e610: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
e620: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
e630: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
e640: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
e650: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
e660: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
e670: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
e680: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
e690: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
e6a0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
e6b0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
e6c0: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
e6d0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
e6e0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
e6f0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
e700: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
e710: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
e720: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
e730: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
e740: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
e750: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
e760: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
e770: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
e780: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
e790: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
e7a0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
e7b0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
e7c0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
e7d0: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
e7e0: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
e7f0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
e800: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
e810: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
e820: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
e830: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
e840: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
e850: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
e860: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
e870: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
e880: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
e890: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
e8a0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
e8b0: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
e8c0: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
e8d0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
e8e0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
e8f0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
e900: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
e910: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
e920: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
e930: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
e940: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
e950: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
e960: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
e970: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
e980: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
e990: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
e9a0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
e9b0: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
e9c0: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
e9d0: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
e9e0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
e9f0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
ea00: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
ea10: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
ea20: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
ea30: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
ea40: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
ea50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
ea60: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
ea70: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
ea80: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
ea90: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
eaa0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
eab0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
eac0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
ead0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
eae0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
eaf0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
eb00: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
eb10: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
eb20: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
eb30: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
eb40: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
eb50: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
eb60: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
eb70: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
eb80: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
eb90: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
eba0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
ebb0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
ebc0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
ebd0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
ebe0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
ebf0: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
ec00: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
ec10: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
ec20: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
ec30: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
ec40: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
ec50: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
ec60: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
ec70: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
ec80: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
ec90: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
eca0: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
ecb0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
ecc0: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
ecd0: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
ece0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
ecf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
ed00: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
ed10: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
ed20: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
ed30: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
ed40: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
ed50: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
ed60: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
ed70: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
ed80: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
ed90: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
eda0: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
edb0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
edc0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
edd0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
ede0: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
edf0: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
ee00: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
ee10: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
ee20: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
ee30: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ee40: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
ee50: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
ee60: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
ee70: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
ee80: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
ee90: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
eea0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
eeb0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
eec0: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
eed0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
eee0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
eef0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
ef00: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
ef10: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
ef20: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
ef30: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
ef40: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
ef50: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
ef60: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
ef70: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
ef80: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
ef90: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
efa0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
efb0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
efc0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
efd0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
efe0: 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
eff0: 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
f000: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
f010: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
f020: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
f030: 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
f040: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
f050: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
f060: 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
f070: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
f080: 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
f090: 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
f0a0: 2a 2a 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  **.** Changes to
f0b0: 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
f0c0: 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
f0d0: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
f0e0: 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
f0f0: 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
f100: 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
f110: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
f120: 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61  **.** A "row cha
f130: 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
f140: 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
f150: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
f160: 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
f170: 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
f180: 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
f190: 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
f1a0: 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
f1b0: 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
f1c0: 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
f1d0: 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
f1e0: 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
f1f0: 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
f200: 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
f210: 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
f220: 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
f230: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
f240: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
f250: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  ges..**.** A "tr
f260: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
f270: 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
f280: 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
f290: 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
f2a0: 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
f2b0: 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
f2c0: 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
f2d0: 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
f2e0: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
f2f0: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
f300: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
f310: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
f320: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
f330: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
f340: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
f350: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
f360: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
f370: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
f380: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
f390: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
f3a0: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
f3b0: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
f3c0: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
f3d0: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
f3e0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
f3f0: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
f400: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
f410: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
f420: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
f430: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
f440: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
f450: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f460: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f470: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
f480: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
f490: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
f4a0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
f4b0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
f4c0: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
f4d0: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
f4e0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
f4f0: 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c   Thus, when call
f500: 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
f510: 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
f520: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
f530: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
f540: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
f550: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
f560: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
f570: 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
f580: 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
f590: 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68  top level.  With
f5a0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
f5b0: 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
f5c0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
f5d0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
f5e0: 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
f5f0: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
f600: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
f610: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
f620: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
f630: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
f640: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
f650: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
f660: 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
f670: 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
f680: 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
f690: 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
f6a0: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
f6b0: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
f6c0: 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
f6d0: 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
f6e0: 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
f6f0: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
f700: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f710: 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
f720: 61 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  ace and the.** [
f730: 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
f740: 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  agma]..**.** Req
f750: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
f760: 31 32 32 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a  12241] [H12243].
f770: 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
f780: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
f790: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
f7a0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
f7b0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
f7c0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
f7d0: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
f7e0: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
f7f0: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
f800: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
f810: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
f820: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f830: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
f840: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f850: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
f860: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
f870: 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36  d {H12260} <S106
f880: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
f890: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
f8a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
f8b0: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
f8c0: 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
f8d0: 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
f8e0: 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
f8f0: 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
f900: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f910: 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
f920: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
f930: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
f940: 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
f950: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
f960: 72 5d 20 0a 2a 2a 20 63 6f 6e 74 65 78 74 73 20  r] .** contexts 
f970: 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
f980: 20 62 79 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   by [foreign key
f990: 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
f9a0: 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
f9b0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
f9c0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
f9d0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
f9e0: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
f9f0: 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
fa00: 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
fa10: 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
fa20: 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
fa30: 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
fa40: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
fa50: 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
fa60: 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
fa70: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
fa80: 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
fa90: 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
faa0: 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
fab0: 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
fac0: 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
fad0: 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
fae0: 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
faf0: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
fb00: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
fb10: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
fb20: 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
fb30: 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
fb40: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
fb50: 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
fb60: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
fb70: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
fb80: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
fb90: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
fba0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
fbb0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
fbc0: 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
fbd0: 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a  hanges pragma]..
fbe0: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
fbf0: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20  ts:.** [H12261] 
fc00: 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49  [H12263].**.** I
fc10: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
fc20: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
fc30: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
fc40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fc50: 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
fc60: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
fc70: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
fc80: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
fc90: 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
fca0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
fcb0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
fcc0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
fcd0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
fce0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
fcf0: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
fd00: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
fd10: 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
fd20: 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
fd30: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
fd40: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
fd50: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
fd60: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
fd70: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
fd80: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
fd90: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
fda0: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
fdb0: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
fdc0: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
fdd0: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
fde0: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
fdf0: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
fe00: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
fe10: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
fe20: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
fe30: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
fe40: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
fe50: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
fe60: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
fe70: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
fe80: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
fe90: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
fea0: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
feb0: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
fec0: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
fed0: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
fee0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
fef0: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
ff00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ff10: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
ff20: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
ff30: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
ff40: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
ff50: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
ff60: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
ff70: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
ff80: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
ff90: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
ffa0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
ffb0: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
ffc0: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
ffd0: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
ffe0: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
fff0: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
10000 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
10010 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
10020 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
10030 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
10040 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
10050 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
10060 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
10070 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
10080 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
10090 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
100a0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
100b0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
100c0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
100d0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
100e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
100f0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
10100 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
10110 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
10120 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
10130 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
10140 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
10150 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
10160 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
10170 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
10180 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
10190 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77 20  plete.  Any new 
101a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
101b0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
101c0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
101d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
101e0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
101f0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
10200 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
10210 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
10220 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
10230 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
10240 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
10250 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
10260 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
10270 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
10280 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
10290 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
102a0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
102b0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
102c0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
102d0 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
102e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
102f0 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20  pt()..** A call 
10300 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
10310 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
10320 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
10330 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
10340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
10350 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
10360 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
10370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
10380 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
10390 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
103a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
103b0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
103c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
103d0 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b  s:.** [H12271] [
103e0 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12272].**.** If
103f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
10400 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
10410 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
10420 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
10430 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
10440 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
10450 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
10460 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
10470 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
10480 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10490 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
104a0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
104b0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48  t Is Complete {H
104c0 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a  10510} <S70200>.
104d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
104e0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
104f0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
10500 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
10510 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
10520 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
10530 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
10540 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
10550 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
10560 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
10570 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
10580 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
10590 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
105a0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
105b0 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
105c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
105d0 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
105e0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
105f0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
10600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
10610 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
10620 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
10630 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
10640 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
10650 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
10660 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
10670 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
10680 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
10690 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
106a0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
106b0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
106c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
106d0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
106e0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
106f0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
10700 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
10710 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
10720 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
10730 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
10740 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
10750 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
10760 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
10770 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
10780 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63 65  tor.  Whitespace
10790 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
107a0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
107b0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
107c0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
107d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
107e0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
107f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
10800 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20  incomplete.  If 
10810 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
10820 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
10830 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
10840 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
10850 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
10860 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
10870 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
10880 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
10890 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
108a0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
108b0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  t SQL..**.** If 
108c0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
108d0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
108e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
108f0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
10900 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
10910 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
10920 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
10930 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10940 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
10950 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
10960 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
10970 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
10980 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
10990 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
109a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
109b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
109c0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
109d0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
109e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
109f0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
10a00 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
10a10 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ete..**.** Requi
10a20 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31  rements: [H10511
10a30 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a  ] [H10512].**.**
10a40 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
10a50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
10a60 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
10a70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10a80 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
10a90 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
10aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10ab0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
10ac0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
10ad0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
10ae0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
10af0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
10b00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10b10 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
10b20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
10b30 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
10b40 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
10b50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
10b60 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
10b70 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
10b80 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48  E_BUSY Errors {H
10b90 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a  12310} <S40400>.
10ba0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
10bb0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
10bc0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
10bd0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
10be0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
10bf0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
10c00 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
10c10 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
10c20 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
10c30 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
10c40 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  locked..**.** If
10c50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
10c60 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
10c70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10c80 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10c90 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
10ca0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
10cb0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
10cc0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
10cd0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
10ce0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
10cf0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
10d00 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
10d10 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
10d20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
10d30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10d40 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
10d50 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
10d60 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
10d70 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
10d80 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
10d90 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
10da0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65  _handler().  The
10db0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10dc0 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
10dd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
10de0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
10df0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
10e00 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
10e10 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
10e20 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
10e30 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ent.  If the.** 
10e40 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
10e50 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
10e60 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
10e70 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
10e80 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
10e90 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
10ea0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
10eb0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10ec0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
10ed0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
10ee0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
10ef0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
10f00 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
10f10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
10f20 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
10f30 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
10f40 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
10f50 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
10f60 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
10f70 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
10f80 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
10f90 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
10fa0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
10fb0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
10fc0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
10fd0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
10fe0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
10ff0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
11000 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
11010 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
11020 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
11030 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
11040 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11050 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
11060 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
11070 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
11080 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
11090 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
110a0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
110b0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
110c0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
110d0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
110e0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
110f0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
11100 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
11110 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
11120 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
11130 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
11140 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
11150 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
11160 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
11170 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
11180 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
11190 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
111a0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
111b0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
111c0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
111d0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
111e0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
111f0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
11200 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
11210 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
11220 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
11230 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
11240 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
11250 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
11260 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
11270 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
11280 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
11290 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
112a0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
112b0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
112c0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
112d0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
112e0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
112f0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
11300 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
11310 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
11320 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
11330 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
11340 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
11350 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
11360 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
11370 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
11380 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
11390 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
113a0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
113b0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
113c0 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
113d0 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
113e0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
113f0 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
11400 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
11410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
11420 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
11430 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
11440 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
11450 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
11460 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
11470 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
11480 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
11490 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
114a0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
114b0 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
114c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
114d0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
114e0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
114f0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
11500 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
11510 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
11520 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
11530 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
11540 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
11550 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
11560 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
11570 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
11580 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
11590 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
115a0 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
115b0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
115c0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
115d0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
115e0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
115f0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
11600 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
11610 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
11620 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
11630 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
11640 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
11650 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
11660 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
11670 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
11680 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rtant..**.** The
11690 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
116a0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
116b0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
116c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
116d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
116e0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
116f0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
11700 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
11710 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
11720 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  .  Note that cal
11730 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
11740 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
11750 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
11760 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
11770 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
11780 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
11790 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
117a0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
117b0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
117c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
117d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
117e0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
117f0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
11800 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
11810 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
11820 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52  havior..** .** R
11830 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
11840 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32  [H12311] [H12312
11850 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33  ] [H12314] [H123
11860 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a  16] [H12318].**.
11870 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
11880 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
11890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
118a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
118b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
118c0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
118d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
118e0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
118f0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
11900 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
11910 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
11920 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11930 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
11940 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
11950 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
11960 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
11970 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
11980 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
11990 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
119a0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
119b0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
119c0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
119d0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
119e0 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
119f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
11a00 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
11a10 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
11a20 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
11a30 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
11a40 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32  ccumulated. {H12
11a50 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
11a60 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
11a70 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
11a80 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
11a90 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
11aa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11ab0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
11ac0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
11ad0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
11ae0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
11af0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
11b00 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
11b10 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
11b20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
11b30 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
11b40 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
11b50 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
11b60 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
11b70 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
11b80 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
11b90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11ba0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
11bb0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
11bc0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
11bd0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
11be0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
11bf0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
11c00 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
11c10 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
11c20 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
11c30 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
11c40 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
11c50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
11c60 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32  ** [H12341] [H12
11c70 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f  343] [H12344].*/
11c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
11c90 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
11ca0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
11cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11cc0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
11cd0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
11ce0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
11cf0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
11d00 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
11d10 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
11d20 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
11d30 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
11d40 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
11d50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11d60 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
11d70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
11d80 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
11d90 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
11da0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
11db0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
11dc0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
11dd0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
11de0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
11df0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
11e00 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
11e10 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
11e20 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
11e30 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
11e40 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
11e50 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
11e60 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
11e70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11e80 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
11e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
11ea0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
11eb0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
11ec0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
11ed0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
11ee0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
11ef0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
11f00 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
11f10 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
11f20 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
11f30 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
11f40 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11f50 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
11f60 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
11f70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
11f80 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
11f90 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
11fa0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
11fb0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
11fc0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
11fd0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
11fe0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
11ff0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
12000 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
12010 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
12020 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
12030 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
12040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
12050 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
12060 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
12070 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
12080 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
12090 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
120a0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
120b0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
120c0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
120d0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
120e0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
120f0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
12100 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
12110 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
12120 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
12130 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
12140 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12150 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
12160 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
12170 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
12180 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12190 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
121a0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
121b0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
121c0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
121d0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
121e0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
121f0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
12200 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
12210 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
12220 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
12230 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12240 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
12250 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
12260 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
12270 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
12280 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
12290 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
122a0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
122b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
122c0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
122d0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
122e0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
122f0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
12300 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
12310 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12320 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12330 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
12340 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
12350 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
12360 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
12370 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
12380 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
12390 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
123a0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
123b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
123c0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
123d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
123e0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
123f0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
12400 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
12410 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
12420 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12430 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
12440 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12450 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
12460 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12470 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
12480 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
12490 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
124a0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
124b0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
124c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
124d0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
124e0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
124f0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
12500 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12510 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
12520 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
12530 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12540 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
12550 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
12560 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
12570 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
12580 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
12590 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
125a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
125b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
125c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
125d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
125e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
125f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
12600 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
12610 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12620 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
12630 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
12640 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
12650 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
12660 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
12670 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
12680 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
12690 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
126a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
126b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
126c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
126d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
126e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
126f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12700 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
12710 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
12720 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
12730 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
12740 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
12750 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12760 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
12770 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
12780 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
12790 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
127a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
127b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
127c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
127d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
127e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
127f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
12800 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
12810 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
12820 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
12830 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
12840 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
12850 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
12860 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
12870 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
12880 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
12890 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
128a0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
128b0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d  nts:.** [H12371]
128c0 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37   [H12373] [H1237
128d0 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32  4] [H12376] [H12
128e0 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f  379] [H12382].*/
128f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
12900 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
12910 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
12920 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
12930 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
12940 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
12950 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
12960 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
12970 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
12980 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
12990 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
129a0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
129b0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
129c0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
129d0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
129e0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
129f0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
12a00 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
12a10 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
12a20 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
12a30 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
12a40 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
12a50 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
12a60 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
12a70 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
12a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12a90 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
12aa0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
12ab0 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c  tions {H17400} <
12ac0 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a  S70000><S20000>.
12ad0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
12ae0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
12af0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
12b00 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
12b10 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
12b20 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12b30 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
12b40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
12b50 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
12b60 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
12b70 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
12b80 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
12b90 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
12ba0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
12bb0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
12bc0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
12bd0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
12be0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
12bf0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
12c00 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
12c10 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
12c20 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
12c30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
12c40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12c50 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
12c60 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
12c70 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
12c80 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
12c90 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
12ca0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
12cb0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
12cc0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
12cd0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
12ce0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12cf0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
12d00 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
12d10 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
12d20 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
12d30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12d40 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
12d50 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
12d60 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12d70 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
12d80 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
12d90 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
12da0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
12db0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
12dc0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
12dd0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
12de0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
12df0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
12e00 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
12e10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12e20 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
12e30 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
12e40 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
12e50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12e60 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
12e70 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
12e80 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
12e90 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
12ea0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
12eb0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
12ec0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
12ed0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
12ee0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
12ef0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
12f00 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
12f10 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
12f20 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
12f30 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
12f40 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12f50 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
12f60 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
12f70 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
12f80 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
12f90 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
12fa0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
12fb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
12fc0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12fd0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
12fe0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
12ff0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
13000 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
13010 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
13020 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
13030 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
13040 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
13050 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
13060 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
13070 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
13080 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
13090 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
130a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
130b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
130c0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
130d0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
130e0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
130f0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
13100 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
13110 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
13120 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
13130 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
13140 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
13150 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
13160 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
13170 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
13180 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
13190 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
131a0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
131b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
131c0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
131d0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
131e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
131f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
13200 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
13210 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
13220 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
13230 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
13240 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
13250 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
13260 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
13270 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
13280 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
13290 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
132a0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
132b0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
132c0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
132d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
132e0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
132f0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
13300 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
13310 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
13320 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13330 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13340 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
13350 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
13360 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
13370 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13380 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
13390 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
133a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
133b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
133c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
133d0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
133e0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
133f0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
13400 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
13410 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
13420 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
13430 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
13440 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
13450 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
13460 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13470 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
13480 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
13490 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
134a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
134b0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
134c0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
134d0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
134e0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
134f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13500 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
13510 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
13520 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
13530 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
13540 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13550 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
13560 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
13570 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
13580 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
13590 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
135a0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
135b0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
135c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
135d0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
135e0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
135f0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
13600 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13610 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
13620 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
13630 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
13640 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
13650 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
13660 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
13670 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
13680 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
13690 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
136a0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
136b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
136c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
136d0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
136e0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
136f0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
13700 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
13710 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
13720 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
13730 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
13740 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
13750 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
13760 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
13770 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
13780 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
13790 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
137a0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
137b0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
137c0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
137d0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
137e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
137f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13800 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
13810 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
13820 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13830 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
13840 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
13850 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
13860 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
13870 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
13880 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13890 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
138a0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
138b0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
138c0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
138d0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
138e0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
138f0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
13900 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
13910 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
13920 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
13930 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
13940 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
13950 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
13960 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
13970 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
13980 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
13990 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
139a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
139b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
139c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
139d0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
139e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
139f0 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 31  .** [H17403] [H1
13a00 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a  7406] [H17407].*
13a10 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
13a20 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
13a30 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
13a40 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13a50 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
13a60 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
13a70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
13a80 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
13a90 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
13aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
13ab0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
13ac0 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
13ad0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
13ae0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
13af0 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
13b00 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
13b10 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
13b20 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
13b30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13b40 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
13b50 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
13b60 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
13b70 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
13b80 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
13b90 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
13ba0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
13bb0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
13bc0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
13bd0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
13be0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
13bf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13c00 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
13c10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
13c20 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
13c30 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
13c40 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
13c50 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
13c60 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
13c70 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
13c80 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
13c90 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
13ca0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
13cb0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
13cc0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
13cd0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
13ce0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
13cf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
13d00 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
13d10 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
13d20 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
13d30 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
13d40 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
13d50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
13d60 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
13d70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
13d80 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
13d90 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
13da0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
13db0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
13dc0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
13dd0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
13de0 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
13df0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
13e00 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
13e10 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
13e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
13e30 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
13e40 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
13e50 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
13e60 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
13e70 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
13e80 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
13e90 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
13ea0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
13eb0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
13ec0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
13ed0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
13ee0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
13ef0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
13f00 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
13f10 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
13f20 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
13f30 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
13f40 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
13f50 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
13f60 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
13f70 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
13f80 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
13f90 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
13fa0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
13fb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
13fc0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
13fd0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
13fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
13ff0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
14000 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
14010 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
14020 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14030 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
14040 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
14050 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
14060 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
14070 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14080 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
14090 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
140a0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
140b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
140c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
140d0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
140e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
140f0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
14100 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
14110 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14120 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
14130 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
14140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14160 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
14170 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
14180 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
14190 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
141a0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
141b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
141c0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
141d0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
141e0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
141f0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
14200 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14220 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ()..** sqlite3_r
14230 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
14240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14260 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
14270 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
14280 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
14290 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
142a0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
142b0 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
142c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
142d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
142e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
142f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
14300 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
14310 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
14320 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
14330 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
14340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14350 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
14360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
14370 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
14380 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
14390 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
143a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
143b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
143c0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
143d0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
143e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
143f0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
14400 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
14410 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
14420 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
14430 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
14440 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
14450 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
14460 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65  tation of the me
14470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14480 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a  subsystem uses.*
14490 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  * the malloc(), 
144a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
144b0 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
144c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
144d0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37  library..** {H17
144e0 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
144f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14500 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14510 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
14520 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20  ZE=<i>NNN</i> C 
14530 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
14540 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e  ro (where <i>NNN
14550 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  </i>.** is an in
14560 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c  teger), then SQL
14570 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
14580 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20  tic array of at 
14590 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c  least.** <i>NNN<
145a0 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
145b0 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  e and uses that 
145c0 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66  array for all of
145d0 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20   its dynamic.** 
145e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
145f0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
14600 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  Additional memor
14610 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
14620 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64  ons.** may be ad
14630 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
14640 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
14650 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
14660 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
14670 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
14680 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
14690 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
146a0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
146b0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
146c0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
146d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
146e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
146f0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
14700 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
14710 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
14720 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
14730 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
14740 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
14750 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
14760 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
14770 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
14780 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
14790 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
147a0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
147b0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
147c0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
147d0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
147e0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
147f0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
14800 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
14810 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
14820 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
14830 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
14840 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
14850 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14860 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
14870 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
14880 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
14890 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
148a0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
148b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
148c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
148d0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52  _NOMEM]..**.** R
148e0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
148f0 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30 34  [H17303] [H17304
14900 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37 33  ] [H17305] [H173
14910 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48 31  06] [H17310] [H1
14920 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b  7312] [H17315] [
14930 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33  H17318].** [H173
14940 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48 31  21] [H17322] [H1
14950 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7323].**.** The 
14960 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
14970 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
14980 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
14990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
149a0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
149b0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
149c0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
149d0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
149e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
149f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14a00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
14a10 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
14a20 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
14a30 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
14a40 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
14a50 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
14a60 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
14a70 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
14a80 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
14a90 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
14aa0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
14ab0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
14ac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14ad0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
14ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
14af0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
14b00 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
14b10 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
14b20 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
14b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14b40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14b50 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
14b60 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
14b70 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
14b80 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
14b90 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
14ba0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
14bb0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
14bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14bd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
14be0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
14bf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
14c00 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
14c10 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
14c20 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
14c30 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
14c40 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
14c50 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d  nts:.** [H17371]
14c60 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37   [H17373] [H1737
14c70 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73  4] [H17375].*/.s
14c80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
14c90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14ca0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
14cb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
14cc0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
14cd0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
14ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14cf0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
14d00 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b  mber Generator {
14d10 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e  H17390} <S20000>
14d20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
14d30 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
14d40 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
14d50 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
14d60 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
14d70 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
14d80 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
14d90 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
14da0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
14db0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
14dc0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
14dd0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
14de0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
14df0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
14e00 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
14e10 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
14e20 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
14e30 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
14e40 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
14e50 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
14e60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
14e70 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
14e80 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
14e90 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
14ea0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
14eb0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
14ec0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
14ed0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
14ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
14ef0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
14f00 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
14f10 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
14f20 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
14f30 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
14f40 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
14f50 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
14f60 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
14f70 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
14f80 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
14f90 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
14fa0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
14fb0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
14fc0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
14fd0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
14fe0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
14ff0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
15000 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
15010 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
15020 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
15030 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
15040 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
15050 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a  ts:.** [H17392].
15060 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
15070 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
15080 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
15090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
150a0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
150b0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
150c0 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31  s {H12500} <S701
150d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
150e0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
150f0 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
15100 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
15110 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15120 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15130 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
15140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15150 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  t..** The author
15160 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
15170 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
15180 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
15190 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
151a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
151b0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
151c0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
151d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
151e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
151f0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
15200 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
15210 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
15220 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
15230 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
15240 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
15250 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
15260 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
15270 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
15280 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
15290 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
152a0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
152b0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
152c0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
152d0 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
152e0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
152f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15300 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
15310 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
15320 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
15330 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
15340 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
15350 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
15360 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
15370 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
15380 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
15390 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
153a0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
153b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
153c0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
153d0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  ith an error.  I
153e0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
153f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15400 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
15410 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
15420 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
15430 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
15440 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
15450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
15460 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
15470 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
15480 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
15490 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
154a0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
154b0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
154c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
154d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
154e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
154f0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
15500 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
15510 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e  ted is ok.  When
15520 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
15530 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
15540 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
15550 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
15560 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
15570 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
15580 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
15590 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
155a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
155b0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
155c0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
155d0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
155e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
155f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
15600 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15610 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
15620 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
15630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
15640 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15650 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
15660 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15670 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
15680 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
15690 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
156a0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
156b0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
156c0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
156d0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
156e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
156f0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
15700 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
15710 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
15720 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
15730 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
15740 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
15750 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
15760 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
15770 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
15780 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  zed..**.** If th
15790 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
157a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
157b0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
157c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
157d0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
157e0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
157f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
15800 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
15810 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
15820 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
15830 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
15840 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
15850 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
15860 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
15870 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
15880 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
15890 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
158a0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
158b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
158c0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
158d0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
158e0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
158f0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
15900 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e  ** If the action
15910 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
15920 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
15930 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15940 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
15950 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
15960 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
15970 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
15980 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
15990 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
159a0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
159b0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
159c0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
159d0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
159e0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
159f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15a00 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
15a10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
15a20 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
15a30 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
15a40 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
15a50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
15a60 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
15a70 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
15a80 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
15a90 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
15aa0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
15ab0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
15ac0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
15ad0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
15ae0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
15af0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
15b00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
15b10 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
15b20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
15b30 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
15b40 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
15b50 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
15b60 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
15b70 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
15b80 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
15b90 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
15ba0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
15bb0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
15bc0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
15bd0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
15be0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
15bf0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
15c00 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
15c10 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
15c20 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
15c30 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
15c40 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
15c50 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
15c60 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
15c70 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
15c80 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
15c90 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
15ca0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
15cb0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
15cc0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
15cd0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
15ce0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
15cf0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
15d00 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
15d10 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
15d20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
15d30 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
15d40 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
15d50 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
15d60 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
15d70 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
15d80 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
15d90 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
15da0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
15db0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
15dc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
15dd0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
15de0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
15df0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
15e00 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
15e10 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
15e20 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
15e30 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
15e40 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
15e50 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
15e60 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15e70 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
15e80 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
15e90 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
15ea0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
15eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
15ec0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
15ed0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
15ee0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
15ef0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15f00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
15f10 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
15f20 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
15f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f40 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
15f50 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
15f60 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
15f70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
15f80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15f90 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
15fa0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
15fb0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
15fc0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
15fd0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
15fe0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
15ff0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
16000 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
16010 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
16020 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
16030 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
16040 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
16050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
16060 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
16070 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
16080 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
16090 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61   Note that the a
160a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
160b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
160c0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
160d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
160e0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
160f0 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
16100 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
16110 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
16120 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
16130 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
16140 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
16150 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
16160 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
16170 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
16180 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
16190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
161a0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
161b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
161c0 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
161d0 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ge..**.** Requir
161e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35  ements:.** [H125
161f0 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31  01] [H12502] [H1
16200 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b  2503] [H12504] [
16210 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d  H12505] [H12506]
16220 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31   [H12507] [H1251
16230 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b  0].** [H12511] [
16240 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d  H12512] [H12520]
16250 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32   [H12521] [H1252
16260 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
16270 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16280 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
16290 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
162a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
162b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
162c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
162d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
162e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
162f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
16300 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
16310 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
16320 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
16330 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
16340 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
16350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16360 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
16370 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
16380 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
16390 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
163a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
163b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
163c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
163d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
163e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
163f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
16400 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16410 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
16420 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
16430 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
16440 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
16450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16460 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
16470 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
16480 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
16490 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
164a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
164b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
164c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
164d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
164e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
164f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16500 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
16510 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
16520 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
16530 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16540 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
16550 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
16560 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
16570 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
16580 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
16590 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
165a0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
165b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
165c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
165d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
165e0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
165f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
16600 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
16610 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
16620 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
16630 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
16640 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
16650 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16660 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
16670 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
16680 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
16690 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
166a0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
166b0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
166c0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
166d0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
166e0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
166f0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
16700 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
16710 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
16720 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
16730 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
16740 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
16750 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
16760 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16770 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
16780 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
16790 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
167a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
167b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
167c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
167d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
167e0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
167f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16800 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16810 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
16820 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
16830 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
16840 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
16850 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
16860 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
16870 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
16880 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
16890 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
168a0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
168b0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  L code..**.** Re
168c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
168d0 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d  H12551] [H12552]
168e0 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35   [H12553] [H1255
168f0 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  4].*/./*********
16900 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16910 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16920 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
16930 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
16940 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
16950 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
16960 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
16970 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
16980 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169a0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
169b0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
169c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
169d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
169e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
169f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
16a00 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
16a10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
16a20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
16a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
16a50 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
16a60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
16a70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
16a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16a90 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
16aa0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
16ab0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
16ac0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
16ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16ae0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
16af0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
16b00 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
16b10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
16b30 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
16b40 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
16b50 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
16b60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
16b80 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
16b90 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
16ba0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
16bb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
16bd0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
16be0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
16bf0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16c00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16c10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
16c20 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
16c30 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
16c40 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
16c50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
16c60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
16c70 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
16c80 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
16c90 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
16ca0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16cb0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
16cc0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
16cd0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
16ce0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
16cf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16d00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
16d10 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
16d20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
16d30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
16d40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16d50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
16d60 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
16d70 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
16d80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16d90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16da0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
16db0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
16dc0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
16dd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16df0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
16e00 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
16e10 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
16e20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16e40 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
16e50 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
16e60 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
16e70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e90 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
16ea0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
16eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16ec0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ee0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
16ef0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
16f00 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
16f10 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
16f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f30 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
16f40 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
16f50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
16f60 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
16f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16f80 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
16f90 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
16fa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
16fb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
16fd0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
16fe0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
16ff0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
17000 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
17020 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
17030 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
17040 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
17050 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
17060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
17070 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
17080 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
17090 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
170a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
170b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
170c0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
170d0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
170e0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
170f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17100 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
17110 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
17120 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
17130 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
17140 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
17160 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
17170 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
17180 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17190 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
171a0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
171b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
171c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
171d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
171e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
171f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
17200 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
17210 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17220 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
17230 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17240 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
17250 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
17260 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17270 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
17280 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17290 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
172a0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
172b0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
172c0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
172d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
172e0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
172f0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
17300 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
17310 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
17320 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17330 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
17340 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
17350 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
17360 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17370 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
17380 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
17390 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
173a0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
173b0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
173c0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
173d0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
173e0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
173f0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
17400 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
17410 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
17420 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
17430 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
17440 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17450 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
17460 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
17470 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
17480 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
17490 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
174a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
174b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
174c0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
174d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
174e0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
174f0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
17500 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
17510 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
17520 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
17530 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
17540 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
17550 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
17560 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
17570 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
17580 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
17590 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
175a0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
175b0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
175c0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
175d0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
175e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
175f0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
17600 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
17610 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
17620 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
17630 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
17640 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
17650 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
17660 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
17670 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
17680 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
17690 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
176a0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
176b0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
176c0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
176d0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
176e0 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31  .** [H12281] [H1
176f0 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b  2282] [H12283] [
17700 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d  H12284] [H12285]
17710 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38   [H12287] [H1228
17720 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b  8] [H12289].** [
17730 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54  H12290].*/.SQLIT
17740 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
17750 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
17760 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
17770 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
17780 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
17790 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
177a0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
177b0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
177c0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
177d0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
177e0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
177f0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
17800 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
17810 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
17820 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
17830 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30  ks {H12910} <S60
17840 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  400>.**.** This 
17850 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
17860 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
17870 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
17880 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
17890 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
178a0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
178b0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
178c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
178d0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
178e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
178f0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
17900 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
17910 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
17920 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
17930 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
17940 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
17950 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
17960 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
17970 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
17980 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
17990 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
179a0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
179b0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
179c0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
179d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
179e0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
179f0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
17a00 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
17a10 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
17a20 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75  gress handler mu
17a30 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
17a40 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
17a50 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
17a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17a70 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17a80 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
17a90 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
17aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17ab0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
17ac0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
17ad0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
17ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17af0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
17b00 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
17b10 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
17b20 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ph..**.** Requir
17b30 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
17b40 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31  11] [H12912] [H1
17b50 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b  2913] [H12914] [
17b60 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d  H12915] [H12916]
17b70 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31   [H12917] [H1291
17b80 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  8].**.*/.void sq
17b90 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
17ba0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
17bb0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
17bc0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
17bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
17be0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
17bf0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17c00 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
17c10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
17c20 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
17c30 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
17c40 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
17c50 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
17c60 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
17c70 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
17c80 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
17c90 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
17ca0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
17cb0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
17cc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
17cd0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
17ce0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
17cf0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
17d00 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
17d10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17d20 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
17d30 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
17d40 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
17d50 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
17d60 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
17d70 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
17d80 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
17d90 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
17da0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
17db0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
17dc0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
17dd0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
17de0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
17df0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
17e00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
17e10 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
17e20 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
17e30 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
17e40 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
17e50 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
17e60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
17e70 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
17e80 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
17e90 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
17ea0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
17eb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
17ec0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
17ed0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
17ee0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
17ef0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
17f00 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
17f10 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
17f20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
17f30 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
17f40 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
17f50 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
17f60 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
17f70 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
17f80 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
17f90 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
17fa0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
17fb0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
17fc0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
17fd0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
17fe0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
17ff0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
18000 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
18010 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
18020 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
18030 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18040 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
18050 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
18060 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
18070 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
18080 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
18090 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
180a0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
180b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
180c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
180d0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
180e0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
180f0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
18100 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18110 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
18120 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
18130 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
18140 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
18150 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
18160 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
18170 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
18180 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
18190 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
181a0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
181b0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
181c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
181d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
181e0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
181f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
18200 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
18210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
18220 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
18230 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
18240 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
18250 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
18260 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
18270 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
18280 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
18290 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
182a0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
182b0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
182c0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
182d0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
182e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
182f0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
18300 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18310 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
18320 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
18330 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
18340 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
18350 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
18360 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
18370 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
18380 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
18390 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
183a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
183b0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
183c0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
183d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
183e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
183f0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
18400 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
18410 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
18420 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18430 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
18440 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
18450 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
18460 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
18470 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
18480 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
18490 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
184a0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
184b0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
184c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
184d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
184e0 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
184f0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
18500 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
18510 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18520 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
18530 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
18540 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
18550 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
18560 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
18570 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
18580 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
18590 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
185a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
185b0 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b  FULLMUTEX],.** [
185c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
185d0 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20  EDCACHE] and/or 
185e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
185f0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  REDCACHE] flags,
18600 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
18610 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
18620 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
18630 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
18640 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
18650 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
18660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18670 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
18680 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
18690 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
186a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
186b0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
186c0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
186d0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
186e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
186f0 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b  me.  If the.** [
18700 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
18710 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
18720 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
18730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18740 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
18750 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
18760 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
18770 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
18780 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
18790 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
187a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
187b0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 54 68  tart-time..** Th
187c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
187d0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
187e0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
187f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18800 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
18810 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
18820 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
18830 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
18840 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
18850 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
18860 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
18870 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
18880 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 54 68  ed_cache()].  Th
18890 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
188a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
188b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
188c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
188d0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
188e0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
188f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
18900 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
18910 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nabled..**.** If
18920 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
18930 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
18940 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
18950 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
18960 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
18970 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
18980 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
18990 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
189a0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
189b0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
189c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
189d0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
189e0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
189f0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
18a00 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
18a10 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
18a20 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
18a30 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
18a40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
18a50 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
18a60 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
18a70 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
18a80 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
18a90 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
18aa0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
18ab0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
18ac0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
18ad0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
18ae0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
18af0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
18b00 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
18b10 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
18b20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
18b30 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
18b40 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
18b50 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
18b60 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
18b70 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
18b80 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
18b90 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
18ba0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
18bb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18bc0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
18bd0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
18be0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18bf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
18c00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
18c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
18c20 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
18c30 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
18c40 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
18c50 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
18c60 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
18c70 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
18c80 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
18c90 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
18ca0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
18cb0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
18cc0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
18cd0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
18ce0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
18cf0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
18d00 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
18d10 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
18d20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
18d30 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
18d40 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
18d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
18d60 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
18d70 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
18d80 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
18d90 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
18da0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
18db0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
18dc0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
18dd0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
18de0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
18df0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
18e00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
18e10 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
18e20 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
18e30 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
18e40 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37  * [H12701] [H127
18e50 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31  02] [H12703] [H1
18e60 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b  2704] [H12706] [
18e70 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d  H12707] [H12709]
18e80 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31   [H12711].** [H1
18e90 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b  2712] [H12713] [
18ea0 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d  H12714] [H12717]
18eb0 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32   [H12719] [H1272
18ec0 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69  1] [H12723].*/.i
18ed0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
18ee0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
18ef0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
18f00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
18f10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
18f20 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
18f30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
18f40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
18f50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
18f60 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
18f70 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
18f80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
18f90 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
18fa0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
18fb0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
18fc0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
18fd0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
18fe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18ff0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
19000 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
19010 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
19020 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
19030 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
19040 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
19050 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
19060 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
19070 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
19080 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
19090 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
190a0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
190b0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
190c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
190d0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
190e0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
190f0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
19100 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19110 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
19120 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
19130 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
19140 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
19150 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
19160 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
19170 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
19180 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
19190 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
191a0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
191b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
191c0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
191d0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
191e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
191f0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
19200 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
19210 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
19220 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
19230 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54  is undefined.  T
19240 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
19250 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
19260 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
19270 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
19280 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
19290 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
192a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
192b0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
192c0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
192d0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
192e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
192f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
19300 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
19310 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
19320 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
19330 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
19340 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
19350 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
19360 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
19370 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
19380 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
19390 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
193a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
193b0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
193c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
193d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
193e0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
193f0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
19400 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
19410 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
19420 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
19430 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
19440 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
19450 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
19460 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
19470 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
19480 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
19490 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
194a0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
194b0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
194c0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
194d0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
194e0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
194f0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
19500 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
19510 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
19520 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
19530 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
19540 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
19550 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
19560 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
19570 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
19580 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
19590 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
195a0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
195b0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
195c0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
195d0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
195e0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
195f0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
19600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19610 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
19620 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
19630 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
19640 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
19650 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
19660 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
19670 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
19680 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
19690 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
196a0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
196b0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
196c0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
196d0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
196e0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
196f0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
19700 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
19710 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
19720 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
19730 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
19740 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
19750 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
19760 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
19770 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
19780 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
19790 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
197a0 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  et..**.** Requir
197b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38  ements:.** [H128
197c0 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 31  01] [H12802] [H1
197d0 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b  2803] [H12807] [
197e0 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 5d  H12808] [H12809]
197f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19800 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
19810 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
19820 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
19830 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
19840 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
19850 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
19860 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
19870 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
19880 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
19890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
198a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
198b0 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
198c0 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
198d0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
198e0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
198f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
19900 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
19910 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
19920 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
19930 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
19940 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
19950 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
19960 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
19970 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
19980 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
19990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
199a0 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
199b0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
199c0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
199d0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
199e0 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
199f0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
19a00 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
19a10 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
19a20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
19a30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19a40 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
19a50 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
19a60 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
19a70 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
19a80 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
19a90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
19aa0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
19ab0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
19ac0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
19ad0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
19ae0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
19af0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
19b00 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
19b10 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
19b20 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
19b30 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
19b40 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
19b50 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
19b60 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
19b70 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
19b80 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
19b90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
19ba0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
19bb0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
19bc0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
19bd0 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
19be0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
19bf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
19c00 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
19c10 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
19c20 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
19c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
19c40 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
19c50 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
19c60 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19c70 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
19c80 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
19c90 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
19ca0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
19cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
19cc0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
19cd0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
19ce0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
19cf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d00 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
19d10 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
19d20 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
19d30 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
19d40 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
19d50 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
19d60 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
19d70 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
19d80 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
19d90 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
19da0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19db0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
19dc0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
19dd0 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
19de0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19df0 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
19e00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
19e10 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
19e20 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
19e30 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
19e40 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
19e50 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
19e60 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
19e70 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  YZ there is a .*
19e80 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
19e90 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
19ea0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
19eb0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
19ec0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
19ed0 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  d .** [limits | 
19ee0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e  SQLITE_MAX_XYZ].
19ef0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
19f00 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
19f10 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
19f20 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70  AX_".).** Attemp
19f30 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
19f40 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
19f50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
19f60 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
19f70 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
19f80 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69  he hard upper li
19f90 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74  mit..**.** Run t
19fa0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
19fb0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
19fc0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
19fd0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
19fe0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
19ff0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1a000 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1a010 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1a020 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1a030 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1a040 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1a050 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1a060 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1a070 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
1a080 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1a090 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1a0a0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1a0b0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1a0c0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1a0d0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1a0e0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1a0f0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1a100 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1a110 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1a120 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1a130 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1a140 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1a150 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1a160 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1a170 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1a180 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1a190 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1a1a0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1a1b0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1a1c0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1a1d0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1a1e0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1a1f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1a200 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1a210 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1a220 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1a230 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1a240 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1a250 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1a260 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1a270 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1a280 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1a290 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1a2a0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1a2b0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1a2c0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1a2d0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1a2e0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1a2f0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ases..**.** Requ
1a300 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1a310 32 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b  2762] [H12766] [
1a320 48 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H12769].*/.int s
1a330 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1a340 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1a350 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1a360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1a370 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1a380 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20  gories {H12790} 
1a390 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57  <H12760>.** KEYW
1a3a0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1a3b0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1a3c0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1a3d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1a3e0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1a3f0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1a400 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1a410 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1a420 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1a430 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1a440 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1a450 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1a460 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1a470 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1a480 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1a490 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1a4a0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1a4b0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1a4c0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1a4d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
1a4e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1a4f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a500 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
1a510 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
1a520 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
1a530 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
1a540 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1a550 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1a560 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a570 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1a580 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1a590 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1a5a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1a5b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a5c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a5d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1a5e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1a5f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1a600 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1a610 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
1a620 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1a630 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1a640 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1a650 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1a660 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1a670 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a680 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1a690 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1a6a0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1a6b0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1a6c0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1a6d0 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1a6e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a6f0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1a700 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1a710 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1a720 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1a730 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1a740 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1a750 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a760 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1a770 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1a780 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1a790 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1a7a0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1a7b0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1a7c0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1a7d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1a7e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a7f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1a800 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1a810 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a820 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1a830 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1a840 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1a850 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a860 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1a870 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a880 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
1a890 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
1a8a0 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a  atabases].</dd>.
1a8b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a8c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1a8d0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1a8e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a8f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1a900 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1a910 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1a920 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1a930 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  rators.</dd>.**.
1a940 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a950 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1a960 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1a970 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1a980 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
1a990 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1a9a0 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
1a9b0 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a  be bound.</dd>.*
1a9c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a9d0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1a9e0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1a9f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1aa00 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
1aa10 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
1aa20 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1aa30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1aa40 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
1aa50 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
1aa60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1aa70 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
1aa80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
1aa90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1aaa0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
1aab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1aac0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1aad0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1aae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1aaf0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
1ab00 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1ab10 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1ab20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1ab30 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
1ab40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ab50 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
1ab60 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1ab70 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
1ab80 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
1ab90 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1aba0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
1abb0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
1abc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1abd0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
1abe0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
1abf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1ac00 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
1ac10 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
1ac20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1ac30 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
1ac40 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
1ac50 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1ac60 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
1ac70 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53  ment {H13010} <S
1ac80 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10000>.** KEYWOR
1ac90 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
1aca0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
1acb0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1acc0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1acd0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1ace0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1acf0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1ad00 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1ad10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
1ad20 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1ad30 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
1ad40 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
1ad50 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
1ad60 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
1ad70 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
1ad80 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
1ad90 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1ada0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
1adb0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
1adc0 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
1add0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
1ade0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
1adf0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
1ae00 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1ae10 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
1ae20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
1ae30 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
1ae40 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
1ae50 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ae60 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
1ae70 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
1ae80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ae90 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
1aea0 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
1aeb0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1aec0 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
1aed0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
1aee0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
1aef0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
1af00 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1af10 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
1af20 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
1af30 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
1af40 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1af50 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20  or. If nByte is 
1af60 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1af70 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
1af80 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
1af90 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
1afa0 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
1afb0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1afc0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1afd0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1afe0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1aff0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1b000 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1b010 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1b020 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1b030 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1b040 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1b050 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1b060 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1b070 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1b080 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1b090 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1b0a0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1b0b0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1b0c0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1b0d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1b0e0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1b0f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1b100 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1b110 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1b120 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1b130 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1b140 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70  ytes..**.** If p
1b150 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
1b160 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
1b170 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1b180 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1b190 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
1b1a0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1b1b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1b1c0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1b1d0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
1b1e0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
1b1f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1b200 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1b210 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1b220 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
1b230 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
1b240 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
1b250 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1b260 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1b270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1b280 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1b290 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1b2a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1b2b0 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   If there is an 
1b2c0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1b2d0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1b2e0 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1b2f0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1b300 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1b310 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1b320 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1b330 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1b340 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1b350 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
1b360 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1b370 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1b380 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1b390 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1b3a0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1b3b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1b3c0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1b3d0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1b3e0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
1b3f0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
1b400 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
1b410 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1b420 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65  urned, otherwise
1b430 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1b440 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b450 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b460 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
1b470 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1b480 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
1b490 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
1b4a0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
1b4b0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
1b4c0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
1b4d0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
1b4e0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
1b4f0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1b500 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
1b510 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
1b520 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
1b530 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
1b540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b550 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
1b560 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
1b570 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1b580 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
1b590 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
1b5a0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
1b5b0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
1b5c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b5d0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
1b5e0 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65  behave a differe
1b5f0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
1b600 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
1b610 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
1b620 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1b630 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
1b640 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
1b650 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
1b660 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
1b670 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
1b680 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1b690 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1b6a0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
1b6b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
1b6c0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
1b6d0 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
1b6e0 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
1b6f0 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
1b700 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
1b710 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
1b720 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
1b730 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
1b740 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
1b750 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
1b760 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
1b770 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
1b780 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1b790 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
1b7a0 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
1b7b0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1b7c0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
1b7d0 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
1b7e0 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
1b7f0 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
1b800 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1b810 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
1b820 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
1b830 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
1b840 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
1b850 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
1b860 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
1b870 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
1b880 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1b890 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b8a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
1b8b0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
1b8c0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
1b8d0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1b8e0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
1b8f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
1b900 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
1b910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b920 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
1b930 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
1b940 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
1b950 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
1b960 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
1b970 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
1b980 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1b990 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
1b9a0 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
1b9b0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
1b9c0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
1b9d0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
1b9e0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
1b9f0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
1ba00 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
1ba10 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
1ba20 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1ba30 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
1ba40 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
1ba50 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70  he value of a [p
1ba60 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1ba70 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1ba80 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  e WHERE clause m
1ba90 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ight.** change t
1baa0 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  he query plan fo
1bab0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  r a statement, t
1bac0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
1bad0 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f  t may be.** auto
1bae0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1baf0 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 72  iled (as if ther
1bb00 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 68  e had been a sch
1bb10 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74  ema change) on t
1bb20 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71  he first .** [sq
1bb30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1bb40 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1bb50 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a   change to the .
1bb60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1bb70 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
1bb80 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65  ] of the [parame
1bb90 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ter]. .** </li>.
1bba0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1bbb0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1bbc0 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32  [H13011] [H13012
1bbd0 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30  ] [H13013] [H130
1bbe0 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31  14] [H13015] [H1
1bbf0 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b  3016] [H13019] [
1bc00 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e  H13021].**.*/.in
1bc10 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1bc20 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1bc30 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1bc40 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1bc50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1bc60 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1bc70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1bc80 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1bc90 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1bca0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1bcb0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1bcc0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1bcd0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1bce0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1bcf0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1bd00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1bd10 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1bd20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1bd30 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1bd40 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1bd50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1bd60 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1bd70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1bd80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1bd90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1bda0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1bdb0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1bdc0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1bdd0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1bde0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1bdf0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1be00 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1be10 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1be20 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1be30 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1be40 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1be50 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1be60 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1be70 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1be80 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1be90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1bea0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1beb0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1bec0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1bed0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1bee0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1bef0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1bf00 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1bf10 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1bf20 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1bf30 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1bf40 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1bf50 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1bf60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1bf70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1bf80 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1bf90 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1bfa0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1bfb0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1bfc0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1bfd0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1bfe0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1bff0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1c000 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1c010 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1c020 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1c030 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1c040 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1c050 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1c060 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1c070 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1c080 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1c090 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1c0a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1c0b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1c0c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1c0d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1c0e0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1c0f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1c100 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1c110 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1c120 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1c130 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
1c140 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
1c150 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
1c160 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
1c170 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1c180 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1c190 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1c1a0 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1c1b0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1c1c0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1c1d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1c1e0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1c1f0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1c200 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1c210 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c220 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1c230 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1c240 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1c250 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d  nts:.** [H13101]
1c260 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30   [H13102] [H1310
1c270 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  3].*/.const char
1c280 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1c290 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1c2a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1c2b0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1c2c0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1c2d0 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32  ect {H15000} <S2
1c2e0 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
1c2f0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1c300 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1c310 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1c320 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1c330 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1c340 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c350 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1c360 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1c370 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1c380 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1c390 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1c3a0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1c3b0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1c3c0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56  ues it stores. V
1c3d0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1c3e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c3f0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1c400 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1c410 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1c420 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1c430 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1c440 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1c450 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1c460 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1c470 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1c480 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1c490 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1c4a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1c4b0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1c4c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1c4d0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1c4e0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1c4f0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1c500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1c510 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1c520 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1c530 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1c540 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1c550 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1c560 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1c570 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1c580 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1c590 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1c5a0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1c5b0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1c5c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1c5d0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1c5e0 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1c5f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1c600 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1c610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c620 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1c630 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1c640 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1c650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c660 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1c670 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1c680 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1c690 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1c6a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1c6b0 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1c6c0 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1c6d0 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1c6e0 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1c6f0 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1c700 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1c710 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1c720 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1c730 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1c740 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1c750 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1c760 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1c770 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1c780 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1c790 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1c7a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1c7b0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1c7c0 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1c7d0 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1c7e0 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1c7f0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1c800 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1c810 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1c820 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1c830 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1c840 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1c850 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1c860 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1c870 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c880 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1c890 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1c8a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1c8b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c8c0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1c8d0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1c8e0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1c8f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c900 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
1c910 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1c920 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
1c930 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1c940 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1c950 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c960 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c970 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1c980 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1c990 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1c9a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1c9b0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1c9c0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1c9d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1c9e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1c9f0 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1ca00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1ca10 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1ca20 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1ca30 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1ca40 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1ca50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ca60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1ca70 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1ca80 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1ca90 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1caa0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1cab0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1cac0 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32  t {H16001} <S202
1cad0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  00>.**.** The co
1cae0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1caf0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1cb00 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1cb10 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1cb20 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1cb30 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
1cb40 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1cb50 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
1cb60 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1cb70 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
1cb80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1cb90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
1cba0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1cbb0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1cbc0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1cbd0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
1cbe0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
1cbf0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
1cc00 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1cc10 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
1cc20 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
1cc30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
1cc40 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
1cc50 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
1cc60 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
1cc70 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
1cc80 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
1cc90 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1cca0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
1ccb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1ccc0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
1ccd0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1cce0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1ccf0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1cd00 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
1cd10 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1cd20 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1cd30 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30   {H13500} <S7030
1cd40 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1cd50 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
1cd60 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1cd70 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
1cd80 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
1cd90 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
1cda0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
1cdb0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
1cdc0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
1cdd0 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
1cde0 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
1cdf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ce00 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
1ce10 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
1ce20 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1ce30 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
1ce40 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
1ce50 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
1ce60 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
1ce70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1ce80 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1ce90 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1cea0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1ceb0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1cec0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1ced0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
1cee0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
1cef0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
1cf00 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
1cf10 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
1cf20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
1cf30 6e 74 69 66 65 72 2e 20 20 54 68 65 20 76 61 6c  ntifer.  The val
1cf40 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1cf50 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1cf60 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1cf70 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1cf80 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1cf90 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1cfa0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1cfb0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1cfc0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1cfd0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1cfe0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1cff0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1d000 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1d010 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1d020 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1d030 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1d040 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1d050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d060 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1d070 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1d080 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1d090 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1d0a0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1d0b0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1d0c0 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1d0d0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1d0e0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1d0f0 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1d100 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1d110 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1d120 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1d130 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1d140 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1d150 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1d160 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1d170 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1d180 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1d190 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1d1a0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1d1b0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1d1c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1d1d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1d1e0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1d1f0 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
1d200 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
1d210 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
1d220 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
1d230 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1d240 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1d250 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1d260 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1d270 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1d280 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1d290 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1d2a0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1d2b0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1d2c0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1d2d0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1d2e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1d2f0 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  * In those routi
1d300 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1d310 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1d320 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1d330 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1d340 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1d350 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1d360 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1d370 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1d380 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1d390 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1d3a0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1d3b0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49  characters..** I
1d3c0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1d3d0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1d3e0 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1d3f0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1d400 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1d410 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1d420 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1d430 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1d440 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1d450 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1d460 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1d470 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1d480 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1d490 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1d4a0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1d4b0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1d4c0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1d4d0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1d4e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1d4f0 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1d500 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1d510 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1d520 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1d530 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1d540 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1d550 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1d560 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1d570 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1d580 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1d590 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1d5a0 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1d5b0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1d5c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1d5d0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1d5e0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1d5f0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1d600 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1d610 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1d620 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1d630 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1d640 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1d650 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1d660 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1d670 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1d680 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1d690 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1d6a0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1d6b0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1d6c0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1d6d0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1d6e0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1d6f0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1d700 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1d710 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1d720 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1d730 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1d740 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1d750 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1d760 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1d770 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1d780 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1d790 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1d7a0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1d7b0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65  outines..** A ne
1d7c0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
1d7d0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
1d7e0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
1d7f0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
1d800 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1d810 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1d820 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1d830 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
1d840 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d850 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
1d860 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
1d870 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
1d880 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
1d890 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
1d8a0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1d8b0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1d8c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1d8d0 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
1d8e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1d8f0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1d900 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
1d910 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d920 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1d930 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
1d940 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
1d950 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1d960 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
1d970 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
1d980 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1d990 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
1d9a0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
1d9b0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
1d9c0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
1d9d0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  () fails..** [SQ
1d9e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67  LITE_MISUSE] mig
1d9f0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
1da00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1da10 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61   are called on a
1da20 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68  .** virtual mach
1da30 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20  ine that is the 
1da40 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77  wrong state or w
1da50 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79  hich has already
1da60 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
1da70 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66  .** Detection of
1da80 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c   misuse is unrel
1da90 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74  iable.  Applicat
1daa0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
1dab0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c  depend.** on SQL
1dac0 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72  ITE_MISUSE retur
1dad0 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55  ns.  SQLITE_MISU
1dae0 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  SE is intended t
1daf0 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20  o indicate a.** 
1db00 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  a logic error in
1db10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1db20 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1db30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1db40 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68  ht.** panic rath
1db50 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53  er than return S
1db60 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
1db70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1db80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1db90 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1dba0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1dbb0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1dbc0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1dbd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1dbe0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1dbf0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1dc00 20 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30   [H13506] [H1350
1dc10 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33  9] [H13512] [H13
1dc20 35 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48  515] [H13518] [H
1dc30 31 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20  13521] [H13524] 
1dc40 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33  [H13527].** [H13
1dc50 35 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48  530] [H13533] [H
1dc60 31 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20  13536] [H13539] 
1dc70 5b 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35  [H13542] [H13545
1dc80 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35  ] [H13548] [H135
1dc90 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  51].**.*/.int sq
1dca0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1dcb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1dcc0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1dcd0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1dce0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1dcf0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
1dd00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1dd10 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
1dd20 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1dd30 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1dd40 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
1dd50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
1dd60 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
1dd70 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
1dd80 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
1dd90 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
1dda0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ddb0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1ddc0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
1ddd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1dde0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
1ddf0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1de00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1de10 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
1de20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1de30 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1de40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1de50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1de60 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
1de70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1de80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
1de90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1dea0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
1deb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1dec0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1ded0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1dee0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
1def0 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
1df00 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
1df10 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1df20 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1df30 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
1df40 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
1df50 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1df60 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
1df70 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1df80 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1df90 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1dfa0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1dfb0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1dfc0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1dfd0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1dfe0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1dff0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1e000 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1e010 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1e020 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1e030 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e040 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
1e050 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1e060 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
1e070 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
1e080 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
1e090 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
1e0a0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
1e0b0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
1e0c0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
1e0d0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
1e0e0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
1e0f0 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
1e100 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
1e110 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
1e120 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
1e130 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1e140 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1e150 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1e160 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e170 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
1e180 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1e190 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1e1a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1e1b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1e1c0 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  01].*/.int sqlit
1e1d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e1e0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
1e1f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1e200 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
1e210 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
1e220 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33  r {H13620} <S703
1e230 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
1e240 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1e250 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1e260 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1e270 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  .** [SQL paramet
1e280 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72  er] in a [prepar
1e290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1e2a0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
1e2b0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1e2c0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1e2d0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1e2e0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1e2f0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1e300 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1e310 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1e320 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1e330 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1e340 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1e350 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1e360 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1e370 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1e380 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1e390 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
1e3a0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1e3b0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
1e3c0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
1e3d0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
1e3e0 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65   and are also re
1e3f0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e  ferred to as "an
1e400 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
1e410 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  rs"..**.** The f
1e420 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
1e430 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1e440 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
1e450 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
1e460 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
1e470 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
1e480 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1e490 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
1e4a0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1e4b0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
1e4c0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
1e4d0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
1e4e0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
1e4f0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
1e500 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
1e510 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
1e520 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
1e530 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e540 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1e550 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1e560 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1e570 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1e580 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1e590 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1e5a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e5b0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1e5c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1e5d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1e5e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1e5f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1e600 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  21].*/.const cha
1e610 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1e620 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1e630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e640 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e650 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1e660 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1e670 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
1e680 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
1e690 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
1e6a0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
1e6b0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
1e6c0 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
1e6d0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
1e6e0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
1e6f0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
1e700 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
1e710 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1e720 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1e730 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
1e740 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
1e750 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
1e760 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
1e770 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
1e780 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
1e790 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
1e7a0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
1e7b0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1e7c0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
1e7d0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
1e7e0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
1e7f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e800 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1e810 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1e820 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1e830 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1e840 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e850 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1e860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1e870 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1e880 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  x()]..**.** Requ
1e890 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1e8a0 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3641].*/.int sql
1e8b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e8c0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
1e8d0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
1e8e0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
1e8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1e900 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
1e910 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
1e920 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30  tatement {H13660
1e930 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1e940 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
1e950 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
1e960 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
1e970 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
1e980 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
1e990 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1e9a0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
1e9b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e9c0 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
1e9d0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
1e9e0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
1e9f0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
1ea00 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1ea10 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a  ts:.** [H13661].
1ea20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1ea30 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
1ea40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1ea50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1ea60 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
1ea70 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1ea80 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30   {H13710} <S1070
1ea90 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
1eaa0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1eab0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1eac0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
1ead0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
1eae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1eaf0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1eb00 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
1eb10 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
1eb20 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
1eb30 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
1eb40 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
1eb50 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
1eb60 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1eb70 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a  .** [H13711].*/.
1eb80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1eb90 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
1eba0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1ebb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ebc0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
1ebd0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31  A Result Set {H1
1ebe0 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3720} <S10700>.*
1ebf0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ec00 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
1ec10 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
1ec20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
1ec30 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
1ec40 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1ec50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1ec60 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
1ec70 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
1ec80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1ec90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1eca0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ecb0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
1ecc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
1ecd0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
1ece0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ecf0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
1ed00 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1ed10 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74  ring.  The first
1ed20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1ed30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1ed40 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1ed50 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1ed60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1ed70 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
1ed80 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1ed90 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1eda0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
1edb0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
1edc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
1edd0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
1ede0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
1edf0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
1ee00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ee10 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
1ee20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1ee30 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1ee40 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
1ee50 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
1ee60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
1ee70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1ee80 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
1ee90 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
1eea0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
1eeb0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
1eec0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
1eed0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
1eee0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
1eef0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
1ef00 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
1ef10 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
1ef20 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
1ef30 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1ef40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
1ef50 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
1ef60 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
1ef70 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
1ef80 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
1ef90 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
1efa0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
1efb0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
1efc0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
1efd0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
1efe0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
1eff0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
1f000 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
1f010 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
1f020 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
1f030 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ext..**.** Requi
1f040 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1f050 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48  721] [H13723] [H
1f060 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20  13724] [H13725] 
1f070 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37  [H13726] [H13727
1f080 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1f090 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1f0a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1f0b0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
1f0c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f0d0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
1f0e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f0f0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
1f100 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
1f110 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
1f120 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20  Result {H13740} 
1f130 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1f140 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
1f150 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
1f160 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
1f170 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
1f180 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
1f190 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
1f1a0 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  lt of a [SELECT]
1f1b0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
1f1c0 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
1f1d0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1f1e0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1f1f0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1f200 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1f210 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1f220 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1f230 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
1f240 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
1f250 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
1f260 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
1f270 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1f280 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
1f290 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
1f2a0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1f2b0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
1f2c0 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
1f2d0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
1f2e0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
1f2f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f300 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
1f310 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
1f320 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
1f330 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
1f340 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
1f350 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
1f360 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
1f370 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
1f380 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
1f390 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
1f3a0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
1f3b0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
1f3c0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
1f3d0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
1f3e0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1f3f0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
1f400 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
1f410 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f420 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
1f430 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1f440 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
1f450 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
1f460 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
1f470 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
1f480 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1f490 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
1f4a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
1f4b0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1f4c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1f4d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
1f4e0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
1f4f0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
1f500 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
1f510 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
1f520 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
1f530 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
1f540 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1f550 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
1f560 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
1f570 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1f580 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
1f590 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
1f5a0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
1f5b0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
1f5c0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
1f5d0 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
1f5e0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1f5f0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
1f600 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
1f610 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
1f620 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
1f630 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
1f640 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
1f650 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
1f660 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
1f670 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
1f680 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
1f690 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
1f6a0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
1f6b0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
1f6c0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
1f6d0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
1f6e0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
1f6f0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
1f700 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
1f710 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1f720 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a  **.** {A13751}.*
1f730 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1f740 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1f750 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1f760 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1f770 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1f780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f790 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1f7a0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1f7b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1f7c0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1f7d0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1f7e0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31  ents:.** [H13741
1f7f0 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37  ] [H13742] [H137
1f800 34 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31  43] [H13744] [H1
1f810 33 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b  3745] [H13746] [
1f820 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66  H13748].**.** If
1f830 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1f840 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1f850 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
1f860 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1f870 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
1f880 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
1f890 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
1f8a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
1f8b0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
1f8c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
1f8d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1f8e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1f8f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1f900 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1f910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1f920 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
1f930 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1f940 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1f950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1f960 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
1f970 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1f980 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1f990 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1f9a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1f9b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1f9c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1f9d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
1f9e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1f9f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1fa00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1fa10 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
1fa20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1fa30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1fa40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1fa50 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1fa60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
1fa70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1fa80 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
1fa90 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
1faa0 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37  t {H13760} <S107
1fab0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  00>.**.** The fi
1fac0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1fad0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1fae0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
1faf0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1fb00 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1fb10 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
1fb20 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
1fb30 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
1fb40 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
1fb50 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
1fb60 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
1fb70 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
1fb80 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
1fb90 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
1fba0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
1fbb0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
1fbc0 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
1fbd0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
1fbe0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
1fbf0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
1fc00 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
1fc10 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
1fc20 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1fc30 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1fc40 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
1fc50 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
1fc60 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
1fc70 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
1fc80 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1fc90 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1fca0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1fcb0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
1fcc0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1fcd0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1fce0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
1fcf0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
1fd00 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
1fd10 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
1fd20 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
1fd30 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
1fd40 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
1fd50 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
1fd60 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
1fd70 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
1fd80 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
1fd90 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
1fda0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
1fdb0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
1fdc0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
1fdd0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
1fde0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
1fdf0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
1fe00 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
1fe10 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
1fe20 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
1fe30 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
1fe40 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
1fe50 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
1fe60 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
1fe70 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
1fe80 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
1fe90 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
1fea0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
1feb0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
1fec0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
1fed0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
1fee0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
1fef0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
1ff00 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ues..**.** Requi
1ff10 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1ff20 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48  761] [H13762] [H
1ff30 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13763].*/.const 
1ff40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1ff50 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
1ff60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1ff70 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1ff80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1ff90 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
1ffa0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1ffb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
1ffc0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
1ffd0 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
1ffe0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
1fff0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
20000 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
20010 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
20020 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
20030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20040 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
20050 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
20060 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
20070 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
20080 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
20090 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
200a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
200b0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
200c0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
200d0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
200e0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
200f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
20100 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
20110 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
20120 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
20130 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
20140 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
20150 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
20160 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
20170 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
20180 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
20190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
201a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
201b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
201c0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
201d0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
201e0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
201f0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
20200 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20210 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
20220 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
20230 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
20240 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
20250 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
20260 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
20270 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
20280 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
20290 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
202a0 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
202b0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
202c0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
202d0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
202e0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
202f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
20300 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
20310 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
20320 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
20330 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
20340 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
20350 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
20360 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
20370 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
20380 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
20390 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
203a0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
203b0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
203c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
203d0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
203e0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
203f0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
20400 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
20410 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
20420 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
20430 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
20440 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
20450 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
20460 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
20470 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
20480 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
20490 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
204a0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
204b0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
204c0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
204d0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
204e0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
204f0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
20500 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
20510 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
20520 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
20530 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
20540 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
20550 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
20560 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
20570 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
20580 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
20590 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
205a0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
205b0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
205c0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
205d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
205e0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
205f0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
20600 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
20610 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
20620 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
20630 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
20640 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
20650 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
20660 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
20670 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
20680 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
20690 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
206a0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
206b0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
206c0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
206d0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
206e0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
206f0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
20700 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
20710 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
20720 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
20730 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
20740 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
20750 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
20760 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
20770 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
20780 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
20790 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
207a0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
207b0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
207c0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
207d0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
207e0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
207f0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
20800 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
20810 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
20820 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
20830 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
20840 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
20850 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
20860 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
20870 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
20880 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
20890 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
208a0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
208b0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
208c0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
208d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
208e0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
208f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
20900 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
20910 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
20920 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
20930 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
20940 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
20950 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
20960 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
20970 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
20980 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
20990 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
209a0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
209b0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
209c0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
209d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
209e0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
209f0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
20a00 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
20a10 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
20a20 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
20a30 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
20a40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
20a50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
20a60 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
20a70 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
20a80 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
20a90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
20aa0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
20ab0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
20ac0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
20ad0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
20ae0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
20af0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
20b00 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
20b10 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
20b20 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
20b30 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
20b40 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
20b50 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
20b60 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
20b70 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
20b80 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
20b90 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
20ba0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
20bb0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
20bc0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
20bd0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
20be0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
20bf0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
20c00 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
20c10 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
20c20 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
20c30 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
20c40 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
20c50 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
20c60 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
20c70 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
20c80 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
20c90 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
20ca0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
20cb0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
20cc0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
20cd0 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
20ce0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
20cf0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
20d00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20d10 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
20d20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
20d30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20d40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
20d50 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
20d60 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
20d70 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
20d80 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
20d90 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
20da0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
20db0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
20dc0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
20dd0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
20de0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
20df0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
20e00 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33  * [H13202] [H153
20e10 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31  04] [H15306] [H1
20e20 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a  5308] [H15310].*
20e30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
20e40 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
20e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20e60 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
20e70 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
20e80 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
20e90 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
20ea0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
20eb0 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
20ec0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
20ed0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
20ee0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
20ef0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d  nts:.** [H13771]
20f00 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74   [H13772].*/.int
20f10 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
20f20 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
20f30 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
20f40 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
20f50 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
20f60 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31   {H10265} <S1011
20f70 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45  0><S10120>.** KE
20f80 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
20f90 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36  EXT.**.** {H1026
20fa0 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  6} Every value i
20fb0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
20fc0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
20fd0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
20fe0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
20ff0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
21000 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
21010 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
21020 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
21030 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
21040 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
21050 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
21060 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
21070 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
21080 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
21090 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
210a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
210b0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
210c0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
210d0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
210e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
210f0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
21100 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
21110 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
21120 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
21130 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
21140 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
21150 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
21160 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
21170 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
21180 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
21190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
211a0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
211b0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
211c0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
211d0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
211e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
211f0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
21200 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
21210 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
21220 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
21230 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
21240 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
21250 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
21260 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
21270 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
21280 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b  s From A Query {
21290 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e  H13800} <S10700>
212a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
212b0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
212c0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
212d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
212e0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
212f0 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61  t query" interfa
21300 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ce..**.** These 
21310 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21320 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
21330 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
21340 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
21350 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
21360 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
21370 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
21380 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
21390 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
213a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
213b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
213c0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
213d0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
213e0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
213f0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
21400 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21410 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
21420 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
21430 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
21440 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
21450 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
21460 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
21470 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
21480 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
21490 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
214a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
214b0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
214c0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 54 68 65   index 0..** The
214d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
214e0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
214f0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
21500 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
21510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
21520 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
21530 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21540 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
21550 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
21560 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
21570 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
21580 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
21590 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
215a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
215b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
215c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
215d0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
215e0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
215f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
21600 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
21610 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
21620 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
21630 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
21640 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
21650 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
21660 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
21670 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
21680 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21690 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
216a0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
216b0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
216c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
216d0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
216e0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
216f0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
21700 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
21710 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
21720 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
21730 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
21740 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21750 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
21760 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
21770 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
21780 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
21790 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
217a0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
217b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
217c0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
217d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
217e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
217f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21800 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
21810 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
21820 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
21830 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
21840 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
21850 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
21860 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
21870 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
21880 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
21890 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
218a0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
218b0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
218c0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
218d0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
218e0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
218f0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
21900 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
21910 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
21920 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
21930 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
21940 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
21950 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
21960 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
21970 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
21980 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
21990 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
219a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
219b0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
219c0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
219d0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
219e0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
219f0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
21a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
21a10 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
21a20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
21a30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
21a40 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
21a50 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
21a60 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
21a70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
21a80 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
21a90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
21aa0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
21ab0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
21ac0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
21ad0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
21ae0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
21af0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
21b00 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
21b10 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
21b20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
21b30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
21b40 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
21b50 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
21b60 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
21b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21b80 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
21b90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
21ba0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
21bb0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
21bc0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
21bd0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
21be0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
21bf0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
21c00 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
21c10 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
21c20 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
21c30 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
21c40 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
21c50 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
21c60 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
21c70 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
21c80 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
21c90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
21ca0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
21cb0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
21cc0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
21cd0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
21ce0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
21cf0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
21d00 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
21d10 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
21d20 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
21d30 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
21d40 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
21d50 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
21d60 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
21d70 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
21d80 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
21d90 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
21da0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
21db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21dc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21dd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
21de0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
21df0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
21e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
21e10 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
21e20 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
21e30 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
21e40 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
21e50 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
21e60 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
21e70 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
21e80 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
21e90 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
21ea0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
21eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
21ec0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
21ed0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
21ee0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
21ef0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
21f00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
21f10 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
21f20 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
21f30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
21f40 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
21f50 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
21f60 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
21f70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
21f80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
21f90 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
21fa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21fb0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
21fc0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
21fd0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
21fe0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
21ff0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
22000 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
22010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
22020 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
22030 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
22040 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
22050 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
22060 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
22070 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
22080 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
22090 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
220a0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
220b0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
220c0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
220d0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
220e0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
220f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
22100 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
22110 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
22120 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
22130 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
22140 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
22150 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
22160 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
22170 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
22180 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
22190 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
221a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
221b0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
221c0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
221d0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
221e0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
221f0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
22200 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
22210 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
22220 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
22230 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
22240 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
22250 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
22260 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
22270 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
22280 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
22290 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
222a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
222b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
222c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
222d0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
222e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
222f0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
22300 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
22310 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
22320 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
22330 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
22340 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
22350 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
22360 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
22370 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22380 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
22390 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
223a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
223b0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
223c0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
223d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
223e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
223f0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
22400 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
22410 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
22420 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
22430 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
22440 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
22450 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
22460 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
22470 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
22480 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
22490 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
224a0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
224b0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
224c0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
224d0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
224e0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
224f0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
22500 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
22510 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
22520 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
22530 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
22540 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22550 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
22560 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
22570 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
22580 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
22590 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
225a0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
225b0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
225c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
225d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
225e0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
225f0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
22600 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
22610 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
22620 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
22630 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
22640 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
22650 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
22660 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
22670 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
22680 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
22690 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
226a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
226b0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
226c0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
226d0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
226e0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
226f0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
22700 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
22710 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
22720 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
22730 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
22740 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
22750 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
22760 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
22770 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
22780 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
22790 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
227a0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
227b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
227c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
227d0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
227e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
227f0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
22800 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
22810 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
22820 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
22830 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
22840 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
22850 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
22860 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
22870 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
22880 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
22890 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
228a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
228b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
228c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
228d0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
228e0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
228f0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
22900 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
22910 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
22920 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
22930 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
22940 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
22950 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
22960 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
22970 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
22980 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
22990 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
229a0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
229b0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
229c0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
229d0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
229e0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
229f0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
22a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22a10 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
22a20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
22a30 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
22a40 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
22a50 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
22a60 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
22a70 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
22a80 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
22a90 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
22aa0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
22ab0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
22ac0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
22ad0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
22ae0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
22af0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
22b00 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
22b10 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
22b20 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
22b30 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
22b40 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
22b50 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
22b60 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
22b70 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
22b80 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
22b90 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
22ba0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
22bb0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
22bc0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
22bd0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
22be0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
22bf0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
22c00 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
22c10 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
22c20 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
22c30 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
22c40 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
22c50 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
22c60 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
22c70 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
22c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22c90 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
22ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22cb0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
22cc0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
22cd0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
22ce0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22cf0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
22d00 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
22d10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
22d20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
22d30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22d40 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
22d50 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
22d60 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
22d70 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
22d80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
22d90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22da0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
22db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22dc0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
22dd0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
22de0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
22df0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
22e00 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
22e10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
22e20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22e30 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
22e40 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
22e50 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
22e60 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
22e70 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
22e80 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
22e90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
22ea0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
22eb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
22ec0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
22ed0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
22ee0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
22ef0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
22f00 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
22f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22f20 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
22f30 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
22f40 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
22f50 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
22f60 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
22f70 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
22f80 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
22f90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
22fa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22fb0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22fc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
22fd0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
22fe0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
22ff0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
23000 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
23010 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
23020 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
23030 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
23040 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
23050 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
23060 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
23070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23080 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
23090 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
230a0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
230b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
230c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
230d0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
230e0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
230f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
23100 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
23110 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
23120 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
23130 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
23140 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
23150 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
23160 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
23170 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
23180 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
23190 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
231a0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
231b0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
231c0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52  _NOMEM]..**.** R
231d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
231e0 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36  [H13803] [H13806
231f0 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38  ] [H13809] [H138
23200 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31  12] [H13815] [H1
23210 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b  3818] [H13821] [
23220 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38  H13824].** [H138
23230 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a  27] [H13830].*/.
23240 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
23260 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23270 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
23280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23290 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
232a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
232b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
232c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
232d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
232e0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
232f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
23300 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23310 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
23320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
23330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23340 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
23350 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
23360 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
23370 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23380 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
23390 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
233a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
233b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
233c0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
233d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
233e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
233f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
23400 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
23410 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
23420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23430 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
23440 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
23450 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
23460 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
23470 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
23480 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
23490 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
234a0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
234b0 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30  00} <S70300><S30
234c0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  100>.**.** The s
234d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
234e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
234f0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
23500 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23510 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ment]..** If the
23520 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65   statement was e
23530 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
23540 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63  ully or not exec
23550 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
23560 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69  n.** SQLITE_OK i
23570 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65  s returned. If e
23580 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
23590 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
235a0 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
235b0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
235c0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
235d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
235e0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
235f0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
23600 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
23610 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
23620 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
23630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23640 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
23650 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
23660 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  t.** completed e
23670 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
23680 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
23690 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
236a0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
236b0 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
236c0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
236d0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
236e0 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ]..** Incomplete
236f0 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
23700 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
23710 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
23720 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64  celed,.** depend
23730 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
23740 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
23750 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  e.** [error code
23760 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
23770 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
23780 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
23790 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30  ments:.** [H1130
237a0 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69  2] [H11304].*/.i
237b0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
237c0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
237d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
237e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
237f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
23800 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
23810 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3330} <S70300>.*
23820 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23830 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
23840 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
23850 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
23860 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
23870 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
23880 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
23890 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
238a0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
238b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
238c0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
238d0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
238e0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
238f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
23900 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
23910 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
23920 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
23930 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
23940 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
23950 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
23960 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
23970 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20  ** {H11332} The 
23980 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
23990 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
239a0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
239b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
239c0 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20  *          back 
239d0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
239e0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
239f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20  .**.** {H11334} 
23a00 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
23a10 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
23a20 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
23a30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23a40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23a50 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
23a60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
23a70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
23a80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
23a90 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
23aa0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
23ab0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
23ac0 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20   on S,.**       
23ad0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
23ae0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
23af0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
23b00 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49  **.** {H11336} I
23b10 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
23b20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
23b30 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
23b40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23b50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23b60 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
23b70 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
23b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
23b90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
23ba0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
23bb0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
23bc0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  e]..**.** {H1133
23bd0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
23be0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
23bf0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
23c00 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
23c10 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e  *          of an
23c20 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
23c30 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
23c40 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
23c50 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
23c60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
23c70 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
23c80 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
23c90 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
23ca0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
23cb0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31   Functions {H161
23cc0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20  00} <S20200>.** 
23cd0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
23ce0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
23cf0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
23d00 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
23d10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23d20 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
23d30 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
23d40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23d50 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
23d60 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
23d70 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
23d80 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
23d90 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
23da0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
23db0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
23dc0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
23dd0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
23de0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
23df0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
23e00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
23e10 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
23e20 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
23e30 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
23e40 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  * two is that th
23e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
23e60 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  er, the name of 
23e70 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
23e80 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
23e90 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
23ea0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73  d in UTF-8 for s
23eb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
23ec0 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
23ed0 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  -16.** for sqlit
23ee0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
23ef0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
23f00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23f10 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
23f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
23f30 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
23f40 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
23f50 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20  o be added.  If 
23f60 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d  a single program
23f70 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
23f80 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
23f90 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72  connection inter
23fa0 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20  nally, then SQL 
23fb0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
23fc0 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
23fd0 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20  ally to.** each 
23fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23ff0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
24000 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
24010 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
24020 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
24030 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
24040 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
24050 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
24060 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
24070 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
24080 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20  exclusive of.** 
24090 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
240a0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
240b0 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
240c0 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
240d0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
240e0 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d  ters.  Any attem
240f0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
24100 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
24110 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
24120 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
24130 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e  LITE_ERROR] bein
24140 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
24150 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  * The third para
24160 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
24170 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
24180 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
24190 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
241a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
241b0 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
241c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
241d0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
241e0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
241f0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
24200 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
24210 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
24220 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
24230 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
24240 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
24250 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24260 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
24270 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
24280 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
24290 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
242a0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
242b0 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
242c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
242d0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
242e0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
242f0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
24300 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
24310 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
24320 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
24330 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
24340 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
24350 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69    Any SQL functi
24360 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
24370 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65  n should be able
24380 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b   to work.** work
24390 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
243a0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
243b0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
243c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
243d0 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
243e0 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
243f0 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
24400 6f 74 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69  other.  An appli
24410 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
24420 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
24430 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
24440 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24450 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
24460 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
24470 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
24480 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
24490 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
244a0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
244b0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
244c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
244d0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
244e0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
244f0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
24500 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
24510 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
24520 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
24530 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
24540 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
24550 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
24560 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
24570 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
24580 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
24590 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
245a0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
245b0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
245c0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
245d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
245e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
245f0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
24600 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
24610 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
24620 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
24630 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
24640 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
24650 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
24660 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
24670 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
24680 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
24690 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
246a0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
246b0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
246c0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
246d0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
246e0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
246f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
24700 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
24710 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
24720 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
24730 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
24740 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
24750 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
24760 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
24770 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
24780 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
24790 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
247a0 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
247b0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
247c0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
247d0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
247e0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
247f0 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
24800 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
24810 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
24820 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
24830 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
24840 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
24850 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
24860 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
24870 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
24880 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
24890 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
248a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
248b0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
248c0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
248d0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
248e0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
248f0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
24900 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
24910 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
24920 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
24930 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
24940 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
24950 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
24960 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
24970 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
24980 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
24990 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
249a0 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70    A function imp
249b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
249c0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
249d0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
249e0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
249f0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
24a00 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
24a10 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
24a20 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66  ative nArg.  A f
24a30 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
24a40 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
24a50 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
24a60 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
24a70 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
24a80 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
24a90 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
24aa0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
24ab0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
24ac0 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e    .** A function
24ad0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
24ae0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
24af0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
24b00 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
24b10 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
24b20 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
24b30 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
24b40 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
24b50 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
24b60 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
24b70 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75  *.** Built-in fu
24b80 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
24b90 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
24ba0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
24bb0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
24bc0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70  ** The first app
24bd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24be0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
24bf0 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72   given name over
24c00 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69  rides all.** bui
24c10 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
24c20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  in the same [dat
24c30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24c40 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  ] with the same 
24c50 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75  name..** Subsequ
24c60 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
24c70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
24c80 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
24c90 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
24ca0 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
24cb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
24cc0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
24cd0 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
24ce0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
24cf0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
24d00 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
24d10 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41  ncoding..**.** A
24d20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
24d30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
24d40 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
24d50 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
24d60 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
24d70 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
24d80 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
24d90 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
24da0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
24db0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
24dc0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
24dd0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
24de0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
24df0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
24e00 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
24e10 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d  nts:.** [H16103]
24e20 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30   [H16106] [H1610
24e30 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36  9] [H16112] [H16
24e40 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48  118] [H16121] [H
24e50 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33  16127].** [H1613
24e60 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36  0] [H16133] [H16
24e70 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48  136] [H16139] [H
24e80 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16142].*/.int sq
24e90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24ea0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
24eb0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
24ec0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
24ed0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
24ee0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
24ef0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
24f00 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
24f10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
24f20 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24f30 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
24f40 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
24f50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
24f60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
24f70 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
24f80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
24f90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
24fa0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
24fb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
24fc0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
24fd0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
24fe0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
24ff0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
25000 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
25010 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
25020 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
25030 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
25040 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
25050 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
25060 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
25070 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
25080 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
25090 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
250a0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
250b0 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36  Encodings {H1026
250c0 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36  7} <S50200> <H16
250d0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
250e0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
250f0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
25100 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
25110 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
25120 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
25130 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
25140 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
25150 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
25160 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25170 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
25180 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
25190 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
251a0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
251b0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
251c0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
251d0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
251e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
251f0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
25200 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
25210 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25220 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
25230 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
25240 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
25250 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
25260 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
25270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25280 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
25290 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
252a0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
252b0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
252c0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
252d0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
252e0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
252f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
25300 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
25310 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
25320 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
25330 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
25340 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
25350 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
25360 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
25370 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
25380 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
25390 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
253a0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
253b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
253c0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
253d0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
253e0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
253f0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
25400 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
25410 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
25420 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
25430 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
25440 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
25450 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
25460 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
25470 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
25480 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
25490 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
254a0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
254b0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
254c0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
254d0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
254e0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
254f0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
25500 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
25510 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
25520 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
25530 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
25540 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
25550 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
25560 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
25570 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
25580 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
25590 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
255a0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
255b0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
255c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
255d0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48  ameter Values {H
255e0 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15100} <S20200>.
255f0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
25600 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
25610 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
25620 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
25630 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
25640 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
25650 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
25660 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
25670 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
25680 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
25690 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
256a0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
256b0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
256c0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
256d0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
256e0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
256f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25700 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
25710 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25720 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
25730 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
25740 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
25750 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
25760 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
25770 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
25780 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
25790 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
257a0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
257b0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
257c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
257d0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
257e0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
257f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
25800 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
25810 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
25820 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
25830 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
25840 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
25850 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
25860 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
25870 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
25880 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
25890 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
258a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
258b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
258c0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
258d0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
258e0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
258f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25900 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
25910 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
25920 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
25930 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25940 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
25950 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
25960 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
25970 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
25980 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
25990 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
259a0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
259b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
259c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
259d0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
259e0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
259f0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
25a00 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
25a10 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
25a20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
25a30 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
25a40 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
25a50 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
25a60 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
25a70 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
25a80 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
25a90 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
25aa0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
25ab0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
25ac0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
25ad0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
25ae0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
25af0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
25b00 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
25b10 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
25b20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25b30 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
25b40 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
25b50 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
25b60 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
25b70 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
25b80 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
25b90 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
25ba0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
25bb0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
25bc0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
25bd0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
25be0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
25bf0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
25c00 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
25c10 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
25c20 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
25c30 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
25c40 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
25c50 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
25c60 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
25c70 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
25c80 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
25c90 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
25ca0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
25cb0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
25cc0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
25cd0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
25ce0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
25cf0 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
25d00 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
25d10 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
25d20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
25d30 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
25d40 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
25d50 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
25d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25d70 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
25d80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25d90 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
25da0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
25db0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
25dc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
25dd0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
25de0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
25df0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
25e00 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
25e10 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
25e20 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
25e30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25e40 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
25e50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
25e60 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
25e70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25e80 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
25e90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25ea0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
25eb0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
25ec0 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b  s:.** [H15103] [
25ed0 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d  H15106] [H15109]
25ee0 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31   [H15112] [H1511
25ef0 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35  5] [H15118] [H15
25f00 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a  121] [H15124].**
25f10 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33   [H15127] [H1513
25f20 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35  0] [H15133] [H15
25f30 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  136].*/.const vo
25f40 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
25f50 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
25f60 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
25f70 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
25f80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25f90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
25fa0 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
25fb0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
25fc0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
25fd0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
25fe0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
25ff0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
26000 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26010 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
26020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
26030 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
26040 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
26050 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
26060 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
26070 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
26080 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
26090 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
260a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
260b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
260c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
260d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
260e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
260f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26100 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
26110 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
26120 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
26130 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
26140 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
26150 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
26160 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
26170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
26180 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
26190 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
261a0 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30   {H16210} <S2020
261b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0>.**.** The imp
261c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
261d0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
261e0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
261f0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
26200 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
26210 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
26220 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
26230 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
26240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
26250 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
26260 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
26270 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74  ed for a.** part
26280 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
26290 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
262a0 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
262b0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
262c0 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  that.** memory, 
262d0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
262e0 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20  inter to it. On 
262f0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
26300 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
26310 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
26320 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
26330 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
26340 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
26350 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  dex,.** the same
26360 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
26370 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  ned. The impleme
26380 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61  ntation of the a
26390 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
263a0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64  .** the returned
263b0 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d   buffer to accum
263c0 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ulate data..**.*
263d0 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  * SQLite automat
263e0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
263f0 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65   allocated buffe
26400 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  r when the aggre
26410 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
26420 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
26430 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
26440 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
26450 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
26460 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
26470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
26480 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
26490 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
264a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
264b0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
264c0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
264d0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
264e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
264f0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
26500 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
26510 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
26520 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
26530 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
26540 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
26550 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
26560 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20  ts:.** [H16211] 
26570 5b 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35  [H16213] [H16215
26580 5d 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f  ] [H16217].*/.vo
26590 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
265a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
265b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
265c0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
265d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
265e0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
265f0 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
26600 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
26610 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
26620 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
26630 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
26640 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
26650 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
26660 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
26670 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
26680 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
26690 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
266a0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
266b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
266c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
266d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
266e0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
266f0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
26700 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
26710 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
26720 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
26730 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
26740 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
26750 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
26760 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
26770 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26780 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
26790 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
267a0 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a  ts:.** [H16243].
267b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
267c0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
267d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
267e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
267f0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
26800 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
26810 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30   {H16250} <S6060
26820 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20200>.**.**
26830 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
26840 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
26850 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26860 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
26870 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
26880 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
26890 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
268a0 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
268b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
268c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
268d0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
268e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
268f0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
26900 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
26910 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
26920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
26930 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
26940 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
26950 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d  nts:.** [H16253]
26960 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
26970 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
26980 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
26990 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
269a0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
269b0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
269c0 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30  ta {H16270} <S20
269d0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  200>.**.** The f
269e0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
269f0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
26a00 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
26a10 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
26a20 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
26a30 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
26a40 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
26a50 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
26a60 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
26a70 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
26a80 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
26a90 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
26aa0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
26ab0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
26ac0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
26ad0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
26ae0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
26af0 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
26b00 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
26b10 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
26b20 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
26b30 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
26b40 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
26b50 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
26b60 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
26b70 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
26b80 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
26b90 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
26ba0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
26bb0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
26bc0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
26bd0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
26be0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
26bf0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
26c00 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
26c10 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
26c20 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
26c30 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
26c40 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
26c50 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
26c60 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
26c70 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
26c80 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
26c90 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
26ca0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26cb0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
26cc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26cd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
26ce0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
26cf0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
26d00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
26d10 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
26d20 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
26d30 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
26d40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26d50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26d60 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  n. If no metadat
26d70 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
26d80 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
26d90 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
26da0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
26db0 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
26dc0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
26dd0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
26de0 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
26df0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
26e00 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
26e10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
26e20 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
26e30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
26e40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26e50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
26e60 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
26e70 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
26e80 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
26e90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
26ea0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
26eb0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
26ec0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
26ed0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26ee0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
26ef0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
26f00 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
26f10 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
26f20 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
26f30 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
26f40 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
26f50 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20  ed..** If it is 
26f60 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
26f70 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
26f80 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
26f90 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
26fa0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
26fb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
26fc0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
26fd0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
26fe0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
26ff0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
27000 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
27010 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
27020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
27030 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
27040 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
27050 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
27060 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
27070 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
27080 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
27090 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
270a0 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
270b0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
270c0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
270d0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
270e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
270f0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
27100 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
27110 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
27120 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
27130 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
27140 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
27150 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
27160 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
27170 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
27180 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
27190 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
271a0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
271b0 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
271c0 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
271d0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
271e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
271f0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
27200 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
27210 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
27220 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
27230 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
27240 31 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20  16272] [H16274] 
27250 5b 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37  [H16276] [H16277
27260 5d 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32  ] [H16278] [H162
27270 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  79].*/.void *sql
27280 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
27290 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
272a0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
272b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
272c0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
272d0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
272e0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
272f0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
27300 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
27310 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
27320 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
27330 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
27340 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
27350 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
27360 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
27370 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
27380 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
27390 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
273a0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
273b0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
273c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
273d0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
273e0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
273f0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
27400 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
27410 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
27420 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
27430 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
27440 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
27450 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
27460 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
27470 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
27480 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
27490 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
274a0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
274b0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
274c0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
274d0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
274e0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
274f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
27500 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
27510 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
27520 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
27530 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
27540 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
27550 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
27560 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
27570 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
27580 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
27590 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
275a0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
275b0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
275c0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
275d0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
275e0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
275f0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
27600 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
27610 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
27620 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
27630 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
27640 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
27650 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
27660 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
27670 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
27680 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
27690 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
276a0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
276b0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
276c0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
276d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
276e0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
276f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27700 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
27710 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27720 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
27730 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
27740 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
27750 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
27760 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
27770 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
27780 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
27790 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
277a0 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
277b0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
277c0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
277d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
277e0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
277f0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
27800 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
27810 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
27820 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
27830 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27840 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
27850 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
27860 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
27870 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27880 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
27890 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
278a0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
278b0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
278c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
278d0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
278e0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
278f0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
27900 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
27910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27920 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
27930 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
27940 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
27950 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
27960 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27970 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
27980 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
27990 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
279a0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
279b0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
279c0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
279d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
279e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
279f0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
27a00 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
27a10 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
27a20 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
27a30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
27a40 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
27a50 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
27a60 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
27a70 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
27a80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27a90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
27aa0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
27ab0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
27ac0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
27ad0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
27ae0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
27af0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
27b00 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
27b10 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
27b20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
27b30 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
27b40 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
27b50 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
27b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27b70 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
27b80 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
27b90 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
27ba0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
27bb0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
27bc0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
27bd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27be0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
27bf0 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
27c00 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
27c10 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
27c20 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
27c30 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
27c40 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
27c50 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
27c60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
27c70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27c80 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
27c90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
27ca0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
27cb0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
27cc0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
27cd0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
27ce0 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
27cf0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
27d00 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
27d10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
27d20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
27d30 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
27d40 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
27d50 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
27d60 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
27d70 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
27d80 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
27d90 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
27da0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
27db0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
27dc0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
27dd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
27de0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
27df0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27e00 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
27e10 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
27e20 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
27e30 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
27e40 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
27e50 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
27e60 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
27e70 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
27e80 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
27e90 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
27ea0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
27eb0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
27ec0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27ed0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
27ee0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
27ef0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
27f00 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
27f10 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
27f20 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
27f30 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
27f40 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
27f50 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
27f60 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
27f70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
27f80 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
27f90 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
27fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27fb0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
27fc0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
27fd0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
27fe0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27ff0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
28000 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
28010 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
28020 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
28030 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
28040 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
28050 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
28060 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
28070 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28080 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
28090 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
280a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
280b0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
280c0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
280d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
280e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
280f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
28100 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
28110 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28120 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
28130 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28140 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
28150 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
28160 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
28170 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
28180 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
28190 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
281a0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
281b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
281c0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
281d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
281e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
281f0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
28200 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
28210 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
28220 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
28230 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
28240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
28250 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
28260 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
28270 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
28280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28290 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
282a0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
282b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
282c0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
282d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
282e0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
282f0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
28300 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
28310 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
28320 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
28330 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28340 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
28350 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28360 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
28370 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
28380 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
28390 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
283a0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
283b0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
283c0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
283d0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
283e0 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
283f0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
28400 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
28410 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
28420 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
28430 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
28440 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28450 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28460 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
28470 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
28480 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28490 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
284a0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
284b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
284c0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
284d0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
284e0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
284f0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
28500 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
28510 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
28520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
28530 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28540 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
28550 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
28560 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
28570 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
28580 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
28590 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
285a0 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
285b0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
285c0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
285d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
285e0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
285f0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
28600 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
28610 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28620 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
28630 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
28640 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
28650 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
28660 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
28670 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
28680 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
28690 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
286a0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
286b0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
286c0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
286d0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
286e0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
286f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
28700 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
28710 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
28720 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
28730 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
28740 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
28750 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
28760 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
28770 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
28780 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
28790 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
287a0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
287b0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
287c0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
287d0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
287e0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
287f0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
28800 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
28810 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
28820 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
28830 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
28840 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
28850 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
28860 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
28870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
28880 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
28890 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
288a0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
288b0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
288c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
288d0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
288e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
288f0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
28900 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
28910 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
28920 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
28930 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
28940 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
28950 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
28960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28970 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
28980 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
28990 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
289a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
289b0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
289c0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
289d0 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
289e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
289f0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
28a00 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
28a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28a20 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
28a30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28a40 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
28a50 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
28a60 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
28a70 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
28a80 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
28a90 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
28aa0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
28ab0 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
28ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28ad0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
28ae0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
28af0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
28b00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28b10 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
28b20 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
28b30 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
28b40 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28b50 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
28b60 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
28b70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
28b80 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
28b90 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
28ba0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
28bb0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
28bc0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
28bd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28be0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
28bf0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
28c00 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
28c10 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
28c20 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
28c30 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
28c40 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
28c50 0a 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31  .** [H16403] [H1
28c60 36 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b  6406] [H16409] [
28c70 48 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d  H16412] [H16415]
28c80 20 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32   [H16418] [H1642
28c90 31 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b  1] [H16424].** [
28ca0 48 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d  H16427] [H16430]
28cb0 20 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33   [H16433] [H1643
28cc0 36 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36  6] [H16439] [H16
28cd0 34 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48  442] [H16445] [H
28ce0 31 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35  16448].** [H1645
28cf0 31 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36  1] [H16454] [H16
28d00 34 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48  457] [H16460] [H
28d10 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73  16463].*/.void s
28d20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
28d30 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
28d40 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
28d50 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
28d60 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
28d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
28d80 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
28d90 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
28da0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
28db0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
28dc0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28dd0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
28de0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28df0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
28e00 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
28e10 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
28e20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
28e30 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
28e40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
28e50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28e60 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
28e70 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
28e80 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
28e90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
28ea0 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
28eb0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
28ec0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ed0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
28ee0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
28ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28f00 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
28f10 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
28f20 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
28f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
28f40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28f50 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
28f60 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
28f70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
28f80 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
28f90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
28fa0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28fb0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
28fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
28fd0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
28fe0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
28ff0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29000 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
29010 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29020 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29030 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
29040 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29050 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
29060 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29070 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29080 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
29090 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
290a0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
290b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
290c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
290d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
290e0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
290f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29100 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
29110 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
29120 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
29130 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d  quences {H16600}
29140 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20300>.**.** 
29150 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
29160 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
29170 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
29180 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
29190 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
291a0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
291b0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
291c0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
291d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
291e0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
291f0 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
29200 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
29210 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
29220 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29230 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
29240 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29250 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
29260 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
29270 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
29280 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
29290 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  . In all cases.*
292a0 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
292b0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
292c0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
292d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
292e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
292f0 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  ay be one of the
29300 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
29310 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
29320 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f  LITE_UTF16LE], o
29330 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
29340 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
29350 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70  hat the user-sup
29360 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65  plied.** routine
29370 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70   expects to be p
29380 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74  assed pointers t
29390 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65  o strings encode
293a0 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a  d using UTF-8,.*
293b0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  * UTF-16 little-
293c0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
293d0 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65  6 big-endian, re
293e0 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a  spectively. The.
293f0 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
29400 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
29410 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74  [SQLITE_UTF16] t
29420 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
29430 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65  the routine.** e
29440 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
29450 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72  to be UTF-16 str
29460 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69  ings in the nati
29470 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f  ve byte order, o
29480 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  r the.** argumen
29490 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45  t can be [SQLITE
294a0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
294b0 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f  if the.** the ro
294c0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
294d0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
294e0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
294f0 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
29500 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
29510 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
29520 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
29530 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
29540 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
29550 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
29560 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
29570 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c  t.  If it is NUL
29580 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73  L, this is the s
29590 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20  ame as deleting 
295a0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
295b0 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68   sequence (so th
295c0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74  at SQLite cannot
295d0 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65   call it anymore
295e0 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20  )..** Each time 
295f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
29600 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
29610 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
29620 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73   is passed.** as
29630 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
29640 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74  eter a copy of t
29650 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
29660 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
29670 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
29680 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29690 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ation() or sqlit
296a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
296b0 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
296c0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67  he remaining arg
296d0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70  uments to the ap
296e0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
296f0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
29700 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
29710 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
29720 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61  by a (length, da
29730 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta) pair and enc
29740 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
29750 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
29760 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
29770 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
29780 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
29790 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
297a0 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e   registered. {EN
297b0 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  D}  The applicat
297c0 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
297d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
297e0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
297f0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
29800 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65   positive if the
29810 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
29820 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65   less than,.** e
29830 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
29840 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
29850 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  ond string. i.e.
29860 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
29870 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
29880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
29890 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
298a0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
298b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
298c0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
298d0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
298e0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
298f0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
29900 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
29910 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
29920 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
29930 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
29940 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
29950 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
29960 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
29970 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29980 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
29990 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
299a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
299b0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f  tion_v2()..** Co
299c0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
299d0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
299e0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
299f0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
29a00 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
29a10 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
29a20 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
29a30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29a40 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
29a50 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
29a60 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
29a70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
29a80 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
29a90 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
29aa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
29ab0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
29ac0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
29ad0 74 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20  ts:.** [H16603] 
29ae0 5b 48 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36  [H16604] [H16606
29af0 5d 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36  ] [H16609] [H166
29b00 31 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31  12] [H16615] [H1
29b10 36 36 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a  6618] [H16621].*
29b20 2a 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36  * [H16624] [H166
29b30 32 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a  27] [H16630].*/.
29b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
29b50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
29b60 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
29b70 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
29b80 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
29b90 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
29ba0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
29bb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
29bc0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
29bd0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
29be0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29bf0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
29c00 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
29c10 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
29c20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
29c30 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
29c40 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
29c50 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
29c60 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
29c70 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
29c80 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
29c90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29ca0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
29cb0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
29cc0 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
29cd0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
29ce0 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
29cf0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
29d00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
29d10 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
29d20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29d30 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
29d40 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36  d Callbacks {H16
29d50 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  700} <S20300>.**
29d60 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
29d70 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
29d80 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
29d90 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
29da0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
29db0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
29dc0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
29dd0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
29de0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
29df0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
29e00 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63  nection] to be c
29e10 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
29e20 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
29e30 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
29e40 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
29e50 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
29e60 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
29e70 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
29e80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
29e90 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
29ea0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
29eb0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
29ec0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
29ed0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
29ee0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
29ef0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31  ed in UTF-8. {H1
29f00 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
29f10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
29f20 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
29f30 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
29f40 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
29f50 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
29f60 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
29f70 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  * A call to eith
29f80 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
29f90 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
29fa0 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
29fb0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
29fc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
29fd0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
29fe0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
29ff0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2a000 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2a010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a020 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2a030 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2a040 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2a050 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a060 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2a070 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2a080 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
2a090 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2a0a0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
2a0b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2a0c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2a0d0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
2a0e0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
2a0f0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
2a100 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2a110 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
2a120 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
2a130 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a140 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2a150 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2a160 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2a170 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
2a180 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2a190 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
2a1a0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
2a1b0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
2a1c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2a1d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
2a1e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a1f0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
2a200 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
2a210 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2a220 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  v2()]..**.** Req
2a230 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
2a240 31 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20  16702] [H16704] 
2a250 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20  [H16706].*/.int 
2a260 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a270 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2a280 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2a290 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2a2a0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2a2b0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2a2c0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2a2d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2a2e0 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2a2f0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2a300 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2a310 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2a320 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2a330 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2a340 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2a350 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2a360 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2a370 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2a380 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2a390 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2a3a0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2a3b0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2a3c0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2a3d0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2a3e0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2a3f0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2a400 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2a410 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a430 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2a440 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2a450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2a460 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2a470 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2a480 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2a490 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2a4a0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2a4b0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2a4c0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2a4d0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2a4e0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2a4f0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2a500 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2a510 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2a520 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2a530 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2a540 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2a550 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2a560 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2a570 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2a580 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2a590 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2a5a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2a5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2a5c0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2a5d0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2a5e0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2a5f0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2a600 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2a610 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a620 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2a630 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2a640 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c   Time {H10530} <
2a650 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
2a660 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
2a670 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
2a680 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
2a690 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
2a6a0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
2a6b0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
2a6c0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2a6d0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
2a6e0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
2a6f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
2a700 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
2a710 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
2a720 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
2a730 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
2a740 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2a750 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2a760 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2a770 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
2a780 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
2a790 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2a7a0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
2a7b0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
2a7c0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
2a7d0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
2a7e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a7f0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
2a800 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
2a810 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
2a820 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
2a830 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
2a840 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
2a850 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  fs] object..**.*
2a860 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2a870 5b 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36  [H10533] [H10536
2a880 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2a890 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
2a8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2a8b0 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
2a8c0 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
2a8d0 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30  ry Files {H10310
2a8e0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
2a8f0 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
2a900 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
2a910 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
2a920 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
2a930 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
2a940 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
2a950 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
2a960 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
2a970 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
2a980 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  y SQLite will be
2a990 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
2a9a0 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74  directory.  If t
2a9b0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2a9c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2a9d0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
2a9e0 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
2a9f0 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
2aa00 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
2aa10 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
2aa20 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
2aa30 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
2aa40 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2aa50 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
2aa60 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
2aa70 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
2aa80 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2aa90 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2aaa0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2aab0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
2aac0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
2aad0 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
2aae0 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
2aaf0 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
2ab00 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
2ab10 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
2ab20 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
2ab30 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
2ab40 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
2ab50 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
2ab60 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
2ab70 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
2ab80 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
2ab90 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
2aba0 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
2abb0 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
2abc0 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
2abd0 2a 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * The [temp_stor
2abe0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2abf0 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2ac00 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2ac10 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2ac20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2ac30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2ac40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2ac50 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a   Furthermore,.**
2ac60 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2ac70 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2ac80 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
2ac90 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
2aca0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
2acb0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
2acc0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
2acd0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2ace0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
2acf0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
2ad00 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
2ad10 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
2ad20 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
2ad30 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
2ad40 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
2ad50 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
2ad60 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
2ad70 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
2ad80 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
2ad90 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
2ada0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
2adb0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2adc0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
2add0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
2ade0 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2adf0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2ae00 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
2ae10 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
2ae20 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
2ae30 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
2ae40 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
2ae50 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
2ae60 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20  uto-Commit Mode 
2ae70 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30  {H12930} <S60200
2ae80 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
2ae90 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
2aea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2aeb0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2aec0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2aed0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2aee0 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2aef0 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2af00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2af10 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2af20 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2af30 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75  espectively.  Au
2af40 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2af50 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
2af60 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
2af70 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2af80 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2af90 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f  ement..** Autoco
2afa0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
2afb0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2afc0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2afd0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2afe0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2aff0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2b000 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2b010 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2b020 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2b030 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
2b040 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
2b050 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
2b060 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
2b070 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
2b080 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
2b090 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
2b0a0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
2b0b0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
2b0c0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
2b0d0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
2b0e0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
2b0f0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
2b100 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2b110 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2b120 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2b130 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2b140 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2b150 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2b160 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
2b170 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
2b180 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
2b190 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2b1a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
2b1b0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
2b1c0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
2b1d0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
2b1e0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
2b1f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
2b200 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31  rements: [H12931
2b210 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39  ] [H12932] [H129
2b220 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a  33] [H12934].*/.
2b230 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
2b240 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
2b250 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
2b260 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
2b270 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
2b280 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
2b290 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d  atement {H13120}
2b2a0 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60600>.**.** 
2b2b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
2b2c0 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
2b2d0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
2b2e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b2f0 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
2b300 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
2b310 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
2b320 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62  ngs.  The [datab
2b330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2b340 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2b350 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2b360 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
2b370 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b380 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20  n] that was the 
2b390 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2b3a0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2b3b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b3c0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2b3d0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2b3e0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2b3f0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2b400 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2b410 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ce..**.** Requir
2b420 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d  ements: [H13123]
2b430 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2b440 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
2b450 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b470 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
2b480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b490 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30   {H13140} <S6060
2b4a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
2b4b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b4c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2b4d0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2b4e0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2b4f0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2b500 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2b510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b520 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74  on] pDb.  If pSt
2b530 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
2b540 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
2b550 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b560 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
2b570 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b580 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
2b590 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
2b5a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
2b5b0 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61  Db.  If no prepa
2b5c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2b5d0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2b5e0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2b5f0 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2b600 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2b610 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2b620 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2b630 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2b640 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2b650 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2b660 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2b670 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2b680 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2b690 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2b6a0 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2b6b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2b6c0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
2b6d0 31 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20  13143] [H13146] 
2b6e0 5b 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32  [H13149] [H13152
2b6f0 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ].*/.sqlite3_stm
2b700 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
2b710 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
2b720 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
2b730 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b740 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
2b750 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
2b760 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2b770 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53  acks {H12950} <S
2b780 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60400>.**.** The
2b790 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2b7a0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2b7b0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2b7c0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2b7d0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2b7e0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2b7f0 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
2b800 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
2b810 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
2b820 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2b830 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2b840 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
2b850 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2b860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b870 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2b880 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  n..** The sqlite
2b890 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2b8a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2b8b0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2b8c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2b8d0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2b8e0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2b8f0 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
2b900 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
2b910 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2b920 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2b930 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b940 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2b950 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2b960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b970 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2b980 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72  ..** The pArg ar
2b990 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
2b9a0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
2b9b0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20  callback..** If 
2b9c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2b9d0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2b9e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2b9f0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2ba00 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2ba10 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2ba20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2ba30 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
2ba40 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
2ba50 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
2ba60 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
2ba70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
2ba80 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2ba90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2baa0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
2bab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2bac0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2bad0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2bae0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2baf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2bb00 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
2bb10 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
2bb20 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2bb30 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2bb40 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2bb50 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2bb60 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2bb70 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2bb80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bb90 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2bba0 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
2bbb0 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
2bbc0 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
2bbd0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
2bbe0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2bbf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2bc00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bc10 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2bc20 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2bc30 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2bc40 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2bc50 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2bc60 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2bc70 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
2bc80 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
2bc90 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
2bca0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
2bcb0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
2bcc0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2bcd0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
2bce0 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70  e [COMMIT].** op
2bcf0 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  eration is allow
2bd00 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e  ed to continue n
2bd10 6f 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65  ormally.  If the
2bd20 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
2bd30 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2bd40 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
2bd50 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
2bd60 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
2bd70 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  K]..** The rollb
2bd80 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
2bd90 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
2bda0 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
2bdb0 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
2bdc0 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
2bdd0 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
2bde0 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
2bdf0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
2be00 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  back..**.** For 
2be10 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2be20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
2be30 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
2be40 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
2be50 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
2be60 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
2be70 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
2be80 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
2be90 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
2bea0 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
2beb0 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
2bec0 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
2bed0 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
2bee0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2bef0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2bf00 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
2bf10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2bf20 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2bf30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2bf40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
2bf50 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ed..** The rollb
2bf60 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
2bf70 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
2bf80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
2bf90 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
2bfa0 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
2bfb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
2bfc0 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
2bfd0 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
2bfe0 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  his </todo>.**.*
2bff0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2c000 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2c010 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
2c020 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2c030 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31  ents:.** [H12951
2c040 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39  ] [H12952] [H129
2c050 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31  53] [H12954] [H1
2c060 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31  2955].** [H12961
2c070 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39  ] [H12962] [H129
2c080 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a  63] [H12964].*/.
2c090 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c0a0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
2c0b0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
2c0c0 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
2c0d0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
2c0e0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
2c0f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
2c100 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2c110 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
2c120 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
2c130 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
2c140 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12970} <S60400>.
2c150 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2c160 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
2c170 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2c180 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
2c190 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
2c1a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2c1b0 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
2c1c0 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
2c1d0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2c1e0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2c1f0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
2c200 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2c210 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
2c220 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2c230 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2c240 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
2c250 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
2c260 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2c270 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2c280 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
2c290 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2c2a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2c2b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
2c2c0 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
2c2d0 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
2c2e0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2c2f0 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69  leted..** The fi
2c300 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2c310 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2c320 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
2c330 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
2c340 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2c350 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65  e_hook()..** The
2c360 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
2c370 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2c380 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
2c390 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
2c3a0 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
2c3b0 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
2c3c0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
2c3d0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
2c3e0 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
2c3f0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
2c400 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  d..** The third 
2c410 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
2c420 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
2c430 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
2c440 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
2c450 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
2c460 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
2c470 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
2c480 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61  row..** The fina
2c490 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2c4a0 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
2c4b0 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
2c4c0 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  ** In the case o
2c4d0 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
2c4e0 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
2c4f0 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
2c500 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
2c510 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2c520 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2c530 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2c540 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2c550 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2c560 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2c570 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2c580 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
2c590 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
2c5a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
2c5b0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
2c5c0 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
2c5d0 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
2c5e0 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2c5f0 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
2c600 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
2c610 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
2c620 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
2c630 20 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61   Nor is the upda
2c640 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
2c650 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
2c660 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
2c670 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
2c680 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
2c690 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
2c6a0 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
2c6b0 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
2c6c0 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
2c6d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
2c6e0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2c6f0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
2c700 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2c710 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2c720 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2c730 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2c740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2c750 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
2c760 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
2c770 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2c780 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2c790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2c7a0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2c7b0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2c7c0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2c7d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2c7e0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2c7f0 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
2c800 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
2c810 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2c820 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2c830 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c840 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2c850 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2c860 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2c870 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2c880 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2c890 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2c8a0 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
2c8b0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
2c8c0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
2c8d0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
2c8e0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
2c8f0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
2c900 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2c910 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2c920 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2c930 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
2c940 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2c950 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
2c960 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  es..**.** Requir
2c970 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
2c980 37 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31  71] [H12973] [H1
2c990 32 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b  2975] [H12977] [
2c9a0 48 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d  H12979] [H12981]
2c9b0 20 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38   [H12983] [H1298
2c9c0 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  6].*/.void *sqli
2c9d0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2c9e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2c9f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2ca00 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2ca10 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2ca20 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2ca30 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2ca40 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2ca50 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2ca60 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b  ed Pager Cache {
2ca70 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e  H10330} <S30900>
2ca80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73  .** KEYWORDS: {s
2ca90 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a  hared cache}.**.
2caa0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2cab0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2cac0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2cad0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2cae0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2caf0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2cb00 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2cb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cb20 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2cb30 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2cb40 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2cb50 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2cb60 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2cb70 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2cb80 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2cb90 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a  ent is false..**
2cba0 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e  .** Cache sharin
2cbb0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
2cbc0 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
2cbd0 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2cbe0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
2cbf0 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
2cc00 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
2cc10 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2cc20 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
2cc30 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
2cc40 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2cc50 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2cc60 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2cc70 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61  ** The cache sha
2cc80 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2cc90 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2cca0 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2ccb0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2ccc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2ccd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2cce0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2ccf0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2cd00 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2cd10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cd20 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2cd30 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2cd40 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2cd50 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2cd60 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2cd70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ned..**.** Virtu
2cd80 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74  al tables cannot
2cd90 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20   be used with a 
2cda0 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57  shared cache.  W
2cdb0 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
2cdc0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
2cdd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2cde0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
2cdf0 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
2ce00 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
2ce10 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
2ce20 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
2ce30 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2ce40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
2ce50 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
2ce60 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
2ce70 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2ce80 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2ce90 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
2cea0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
2ceb0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
2cec0 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2ced0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2cee0 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2cef0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2cf00 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2cf10 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2cf20 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2cf30 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2cf40 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2cf50 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2cf60 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2cf70 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2cf80 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2cf90 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65  e Mode].**.** Re
2cfa0 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
2cfb0 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48  331] [H10336] [H
2cfc0 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a  10337] [H10339].
2cfd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2cfe0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
2cff0 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
2d000 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
2d010 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
2d020 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c  emory {H17340} <
2d030 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2d040 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
2d050 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
2d060 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2d070 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
2d080 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
2d090 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
2d0a0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
2d0b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
2d0c0 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
2d0d0 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
2d0e0 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20  . {END}  Memory 
2d0f0 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
2d100 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
2d110 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
2d120 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
2d130 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
2d140 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
2d150 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2d160 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2d170 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d180 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2d190 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2d1a0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2d1b0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2d1c0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2d1d0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2d1e0 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31  ts: [H17341] [H1
2d1f0 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7342].*/.int sql
2d200 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2d210 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
2d220 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
2d230 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
2d240 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20  p Size {H17350} 
2d250 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
2d260 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
2d270 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74  heap_limit() int
2d280 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
2d290 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20  "soft" limit.** 
2d2a0 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
2d2b0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
2d2c0 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
2d2d0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
2d2e0 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
2d2f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
2d300 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75  quested that wou
2d310 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2d320 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d330 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
2d340 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
2d350 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a  invoked one or.*
2d360 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  * more times to 
2d370 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
2d380 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
2d390 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66  location is perf
2d3a0 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ormed..**.** The
2d3b0 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2d3c0 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
2d3d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c   if [sqlite3_rel
2d3e0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
2d3f0 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75  * cannot free su
2d400 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
2d410 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
2d420 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
2d430 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
2d440 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
2d450 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
2d460 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
2d470 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
2d480 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  **.** A negative
2d490 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
2d4a0 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
2d4b0 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
2d4c0 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
2d4d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
2d4e0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
2d4f0 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
2d500 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
2d510 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54   exhausted..** T
2d520 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2d530 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2d540 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
2d550 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
2d560 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2d570 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2d580 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2d590 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2d5a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2d5b0 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2d5c0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2d5d0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2d5e0 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2d5f0 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
2d600 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2d610 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2d620 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2d630 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2d640 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2d650 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2d660 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2d670 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2d680 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2d690 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2d6a0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2d6b0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2d6c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2d6d0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2d6e0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2d6f0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2d700 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2d710 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2d720 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2d730 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2d740 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2d750 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2d760 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2d770 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2d780 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2d790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2d7a0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2d7b0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2d7c0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2d7d0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2d7e0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2d7f0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2d800 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2d810 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2d820 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b  s:.** [H16351] [
2d830 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d  H16352] [H16353]
2d840 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35   [H16354] [H1635
2d850 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76  5] [H16358].*/.v
2d860 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
2d870 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
2d880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d890 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
2d8a0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
2d8b0 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48  mn Of A Table {H
2d8c0 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a  12850} <S60300>.
2d8d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2d8e0 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2d8f0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2d900 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2d910 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2d920 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2d930 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2d940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d950 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2d960 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2d970 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2d980 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2d990 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
2d9a0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
2d9b0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
2d9c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2d9d0 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
2d9e0 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e  ction. The secon
2d9f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
2da00 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
2da10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2da20 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
2da30 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74  "temp" or an att
2da40 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
2da50 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
2da60 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
2da70 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74  e or NULL. If it
2da80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
2da90 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
2daa0 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
2dab0 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
2dac0 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
2dad0 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
2dae0 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2daf0 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
2db00 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
2db10 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
2db20 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
2db30 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2db40 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2db50 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
2db60 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
2db70 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
2db80 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
2db90 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
2dba0 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
2dbb0 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
2dbc0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
2dbd0 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20  .** Metadata is 
2dbe0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
2dbf0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
2dc00 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
2dc10 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
2dc20 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2dc30 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2dc40 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
2dc50 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
2dc60 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
2dc70 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
2dc80 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2dc90 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
2dca0 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
2dcb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed..**.** <block
2dcc0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2dcd0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2dce0 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
2dcf0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
2dd00 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
2dd10 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
2dd20 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
2dd30 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2dd40 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
2dd50 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
2dd60 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2dd70 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
2dd80 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
2dd90 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
2dda0 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
2ddb0 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2ddc0 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
2ddd0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2dde0 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
2ddf0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
2de00 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2de10 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
2de20 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
2de30 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
2de40 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
2de50 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2de60 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
2de70 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
2de80 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2de90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
2dea0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2deb0 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2dec0 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2ded0 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2dee0 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2def0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2df00 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2df10 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2df20 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2df30 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2df40 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2df50 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
2df60 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
2df70 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
2df80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2df90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2dfa0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2dfb0 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2dfc0 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2dfd0 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2dfe0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2dff0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2e000 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2e010 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2e020 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2e030 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2e040 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2e050 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2e060 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69  lumn. If there i
2e070 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
2e080 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
2e090 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2e0a0 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
2e0b0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2e0c0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2e0d0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
2e0e0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
2e0f0 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
2e100 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
2e110 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
2e120 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
2e130 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
2e140 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
2e150 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
2e160 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
2e170 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  re>.**.** This f
2e180 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
2e190 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
2e1a0 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
2e1b0 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
2e1c0 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
2e1d0 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
2e1e0 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
2e1f0 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
2e200 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
2e210 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
2e220 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2e230 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
2e240 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65  error message le
2e250 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61  ft.** in the [da
2e260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e270 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  n] (to be retrie
2e280 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
2e290 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
2e2a0 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
2e2b0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2e2c0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2e2d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2e2e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2e2f0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2e300 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2e310 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
2e320 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2e330 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
2e340 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
2e350 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2e360 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
2e370 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
2e380 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e390 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
2e3a0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
2e3b0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
2e3c0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
2e3d0 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
2e3e0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
2e3f0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
2e400 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
2e410 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
2e420 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
2e430 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
2e440 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
2e450 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
2e460 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
2e470 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
2e480 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
2e490 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
2e4a0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
2e4b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2e4c0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
2e4d0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2e4e0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
2e4f0 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
2e500 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2e510 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
2e520 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
2e530 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
2e540 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
2e550 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2e560 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
2e570 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
2e580 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e590 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
2e5a0 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53  sion {H12600} <S
2e5b0 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2e5c0 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
2e5d0 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
2e5e0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
2e5f0 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
2e600 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31  e..**.** {H12601
2e610 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2e620 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2e630 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2e640 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2e650 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
2e660 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
2e670 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
2e680 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a  he file zFile..*
2e690 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68  *.** {H12602} Th
2e6a0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
2e6b0 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zProc..**.** {H
2e6c0 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
2e6d0 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
2e6e0 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
2e6f0 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
2e700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
2e710 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
2e720 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
2e730 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34  "..**.** {H12604
2e740 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2e750 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2e760 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
2e770 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2e780 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e    [SQLITE_OK] on
2e790 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
2e7a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
2e7b0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
2e7c0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ong..**.** {H126
2e7d0 30 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20  05} If an error 
2e7e0 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
2e7f0 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
2e800 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
2e810 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64     [sqlite3_load
2e820 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
2e830 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
2e840 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20  tempt to.**     
2e850 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72       fill *pzErr
2e860 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d  Msg with error m
2e870 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
2e880 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
2e890 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
2e8a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2e8b0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d  malloc()]. {END}
2e8c0 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
2e8d0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2e8e0 20 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74     should free t
2e8f0 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61  his memory by ca
2e900 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
2e910 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ree()]..**.** {H
2e920 31 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e  12606} Extension
2e930 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
2e940 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
2e950 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e960 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2e970 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2e980 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
2e990 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20  is API,.**      
2e9a0 20 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e      otherwise an
2e9b0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2e9c0 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
2e9d0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
2e9e0 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
2e9f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ea00 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
2ea10 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
2ea20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ea30 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
2ea40 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
2ea50 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
2ea60 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
2ea70 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
2ea80 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
2ea90 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
2eaa0 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
2eab0 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
2eac0 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
2ead0 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
2eae0 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
2eaf0 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
2eb00 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
2eb10 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2eb20 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
2eb30 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
2eb40 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e  H12620} <S20500>
2eb50 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74  .**.** So as not
2eb60 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
2eb70 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
2eb80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
2eb90 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
2eba0 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
2ebb0 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
2ebc0 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
2ebd0 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
2ebe0 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
2ebf0 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
2ec00 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
2ec10 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
2ec20 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73  lowing API.** is
2ec30 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
2ec40 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
2ec50 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2ec60 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
2ec70 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74  d off..**.** Ext
2ec80 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
2ec90 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
2eca0 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  . See ticket #18
2ecb0 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32  63..**.** {H1262
2ecc0 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  1} Call the sqli
2ecd0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2ece0 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
2ecf0 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
2ed00 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  1.**          to
2ed10 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
2ed20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
2ed30 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
2ed40 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
2ed50 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b           it back
2ed60 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a   off again..**.*
2ed70 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e  * {H12622} Exten
2ed80 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
2ed90 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  off by default..
2eda0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2edb0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2edc0 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
2edd0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
2ede0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2edf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
2ee00 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20  d An Extensions 
2ee10 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30  {H12640} <S20500
2ee20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  >.**.** This API
2ee30 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20   can be invoked 
2ee40 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74  at program start
2ee50 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  up in order to r
2ee60 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  egister.** one o
2ee70 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c  r more staticall
2ee80 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69  y linked extensi
2ee90 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  ons that will be
2eea0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f   available.** to
2eeb0 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61   all new [databa
2eec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e  se connections].
2eed0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2eee0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2eef0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2ef00 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61  e extension in a
2ef10 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a  n array that is.
2ef20 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
2ef30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2ef40 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e  ()].  If you run
2ef50 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63   a memory leak c
2ef60 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75  hecker.** on you
2ef70 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74  r program and it
2ef80 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20   reports a leak 
2ef90 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20  because of this 
2efa0 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a  array, invoke.**
2efb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
2efc0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2efd0 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64  ] prior to shutd
2efe0 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
2eff0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  memory..**.** {H
2f000 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63  12641} This func
2f010 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61  tion registers a
2f020 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  n extension entr
2f030 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a  y point that is.
2f040 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2f050 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
2f060 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
2f070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f080 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
2f090 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69     is opened usi
2f0a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
2f0b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2f0c0 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
2f0d0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2f0e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  _open_v2()]..**.
2f0f0 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c  ** {H12642} Dupl
2f100 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73  icate extensions
2f110 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f   are detected so
2f120 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   calling this ro
2f130 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20  utine.**        
2f140 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73    multiple times
2f150 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65   with the same e
2f160 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d  xtension is harm
2f170 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  less..**.** {H12
2f180 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e  643} This routin
2f190 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
2f1a0 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
2f1b0 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a  ion in an array.
2f1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
2f1d0 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2f1e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2f1f0 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  c()]..**.** {H12
2f200 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
2f210 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
2f220 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
2f230 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2f240 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2f250 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
2f260 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
2f270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2f280 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
2f290 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2f2a0 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30   {H12660} <S2050
2f2b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
2f2c0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2f2d0 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
2f2e0 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
2f2f0 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
2f300 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64  s. {END}  It und
2f310 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
2f320 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b  f all prior.** [
2f330 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
2f340 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e  ension()] calls.
2f350 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20  .**.** {H12661} 
2f360 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2f370 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69  sables all previ
2f380 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
2f390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
2f3a0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2f3b0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32  s..**.** {H12662
2f3c0 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
2f3d0 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
2f3e0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
2f3f0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
2f400 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2f410 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2f420 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
2f430 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
2f440 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
2f450 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
2f460 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
2f470 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
2f480 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
2f490 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2f4a0 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
2f4b0 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
2f4c0 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
2f4d0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
2f4e0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
2f4f0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
2f500 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
2f510 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
2f520 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
2f530 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
2f540 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
2f550 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
2f560 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2f570 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
2f580 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
2f590 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
2f5a0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
2f5b0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
2f5c0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
2f5d0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
2f5e0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
2f5f0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
2f600 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
2f610 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
2f620 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2f630 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
2f640 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
2f650 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2f660 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
2f670 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
2f680 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2f690 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
2f6a0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
2f6b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2f6c0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
2f6d0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
2f6e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f6f0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
2f700 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53  ject {H18000} <S
2f710 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20400>.** KEYWOR
2f720 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
2f730 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
2f740 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50  e module}.** EXP
2f750 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2f760 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
2f770 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
2f780 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61   a a "virtual ta
2f790 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a  ble module", .**
2f7a0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70   defines the imp
2f7b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
2f7c0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2f7d0 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72  ].  .** This str
2f7e0 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20  ucture consists 
2f7f0 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
2f800 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
2f810 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  ..**.** A virtua
2f820 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
2f830 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
2f840 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
2f850 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
2f860 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
2f870 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
2f880 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2f890 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
2f8a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f8b0 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
2f8c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2f8d0 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ule_v2()]..** Th
2f8e0 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
2f8f0 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
2f900 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
2f910 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
2f920 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
2f930 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
2f940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
2f950 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
2f960 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
2f970 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
2f980 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
2f990 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
2f9a0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
2f9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
2f9c0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
2f9d0 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
2f9e0 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
2f9f0 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
2fa00 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
2fa10 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2fa20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
2fa30 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
2fa40 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
2fa50 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
2fa60 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
2fa70 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
2fa80 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
2fa90 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
2faa0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
2fab0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
2fac0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
2fad0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
2fae0 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
2faf0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
2fb00 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
2fb10 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2fb20 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
2fb30 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
2fb40 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
2fb50 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2fb60 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
2fb70 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
2fb80 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2fb90 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
2fba0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
2fbb0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2fbc0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
2fbd0 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
2fbe0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2fbf0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
2fc00 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
2fc10 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
2fc20 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
2fc30 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
2fc40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2fc50 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
2fc60 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
2fc70 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
2fc80 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fc90 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
2fca0 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
2fcb0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2fcc0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
2fcd0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2fce0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
2fcf0 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
2fd00 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
2fd10 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2fd20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
2fd30 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
2fd40 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
2fd50 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
2fd60 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
2fd70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
2fd80 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
2fd90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2fda0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2fdb0 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
2fdc0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2fdd0 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
2fde0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2fdf0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
2fe00 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
2fe10 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2fe20 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
2fe30 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
2fe40 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
2fe50 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
2fe60 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
2fe70 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2fe80 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
2fe90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2fea0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2feb0 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
2fec0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
2fed0 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
2fee0 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
2fef0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
2ff00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
2ff10 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
2ff20 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
2ff30 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e  able Indexing In
2ff40 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30  formation {H1810
2ff50 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b  0} <S20400>.** K
2ff60 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
2ff70 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45  _index_info.** E
2ff80 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
2ff90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2ffa0 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
2ffb0 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
2ffc0 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
2ffd0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
2ffe0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
2fff0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
30000 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
30010 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
30020 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
30030 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
30040 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
30050 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
30060 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
30070 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
30080 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
30090 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
300a0 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
300b0 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
300c0 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
300d0 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  **.** The aConst
300e0 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
300f0 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
30100 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
30110 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a  f the form:.**.*
30120 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50  * <pre>column OP
30130 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a   expr</pre>.**.*
30140 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
30150 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
30160 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54  t;, or &gt;=.  T
30170 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70  he particular op
30180 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f  erator is.** sto
30190 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  red in aConstrai
301a0 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e  nt[].op.  The in
301b0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
301c0 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
301d0 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
301e0 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74  iColumn.  aConst
301f0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
30200 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
30210 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
30220 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
30230 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
30240 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
30250 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
30260 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
30270 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a  f it cannot..**.
30280 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72  ** The optimizer
30290 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
302a0 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20  nverts terms of 
302b0 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f  the form "expr O
302c0 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64  P column".** and
302d0 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d   makes other sim
302e0 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20  plifications to 
302f0 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
30300 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
30310 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79  o.** get as many
30320 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
30330 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72  rms into the for
30340 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73  m shown above as
30350 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68   possible..** Th
30360 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
30370 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
30380 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
30390 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72  terms in the cor
303a0 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61  rect.** form tha
303b0 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70  t refer to the p
303c0 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
303d0 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
303e0 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66  eried..**.** Inf
303f0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
30400 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
30410 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
30420 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45  aOrderBy[]..** E
30430 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
30440 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
30450 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
30460 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
30470 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e  .** The [xBestIn
30480 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74  dex] method must
30490 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e   fill aConstrain
304a0 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e  tUsage[] with in
304b0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
304c0 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65  ut what paramete
304d0 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46  rs to pass to xF
304e0 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49  ilter.  If argvI
304f0 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
30500 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
30510 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
30520 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
30530 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
30540 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
30550 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
30560 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
30570 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e  .  If aConstrain
30580 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
30590 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
305a0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
305b0 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
305c0 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
305d0 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
305e0 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
305f0 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
30600 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
30610 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
30620 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
30630 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
30640 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
30650 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
30660 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  ..** [sqlite3_fr
30670 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
30680 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
30690 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20  and only iff.** 
306a0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
306b0 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
306c0 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
306d0 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
306e0 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c  utput from [xFil
306f0 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c  ter]/[xNext] wil
30700 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
30710 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
30720 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
30730 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
30740 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
30750 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
30760 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
30770 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
30780 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
30790 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
307a0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
307b0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
307c0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
307d0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
307e0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
307f0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
30800 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
30810 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
30820 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
30830 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
30840 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
30850 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
30860 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
30870 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
30880 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
30890 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
308a0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
308b0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
308c0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
308d0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
308e0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
308f0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
30900 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
30910 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
30920 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
30930 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
30940 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
30950 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
30960 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
30970 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
30980 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
30990 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
309a0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
309b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
309c0 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
309d0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
309e0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
309f0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
30a00 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
30a10 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
30a20 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
30a30 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
30a40 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
30a50 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
30a60 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
30a70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
30a80 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
30a90 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
30aa0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
30ab0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
30ac0 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
30ad0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
30ae0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
30af0 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
30b00 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
30b10 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
30b20 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
30b30 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
30b40 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
30b50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30b60 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
30b70 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
30b80 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
30b90 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
30ba0 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
30bb0 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
30bc0 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
30bd0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
30be0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
30bf0 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
30c00 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
30c10 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
30c20 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
30c30 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
30c40 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
30c50 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
30c60 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
30c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30c80 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
30c90 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
30ca0 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
30cb0 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
30cc0 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
30cd0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
30ce0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
30cf0 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
30d00 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
30d10 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
30d20 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
30d30 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
30d40 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
30d50 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
30d60 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
30d70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
30d80 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
30d90 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
30da0 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
30db0 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
30dc0 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
30dd0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
30de0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30df0 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
30e00 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30e10 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
30e20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
30e30 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30e40 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
30e50 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30e60 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
30e70 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
30e80 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
30e90 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
30ea0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
30eb0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
30ec0 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
30ed0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
30ee0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
30ef0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48  mplementation {H
30f00 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18200} <S20400>.
30f10 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
30f20 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
30f30 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
30f40 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69  gister a new [vi
30f50 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30f60 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64  le] name..** Mod
30f70 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ule names must b
30f80 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66  e registered bef
30f90 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20  ore.** creating 
30fa0 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
30fb0 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20  able] using the 
30fc0 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72  module, or befor
30fd0 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65  e using a.** pre
30fe0 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61  existing [virtua
30ff0 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65  l table] for the
31000 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54   module..**.** T
31010 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69  he module name i
31020 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20  s registered on 
31030 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
31040 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
31050 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  ied.** by the fi
31060 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
31070 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
31080 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
31090 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
310a0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
310b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
310c0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
310d0 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  o.** the impleme
310e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ntation of the [
310f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
31100 64 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75  dule].   The fou
31110 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
31120 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
31130 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69   client data poi
31140 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
31150 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69  sed through.** i
31160 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65  nto the [xCreate
31170 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
31180 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
31190 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
311a0 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e  dule.** when a n
311b0 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ew virtual table
311c0 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65   is be being cre
311d0 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61  ated or reinitia
311e0 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  lized..**.** Thi
311f0 73 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20  s interface has 
31200 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
31210 20 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69   effect as calli
31220 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
31230 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
31240 29 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63  )] with a NULL c
31250 6c 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72  lient data destr
31260 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  uctor..*/.SQLITE
31270 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
31280 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31290 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
312a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
312b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
312c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
312d0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
312e0 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
312f0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
31300 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
31310 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
31320 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
31330 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
31340 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
31350 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
31360 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20  lientData       
31370 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
31380 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
31390 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
313a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
313b0 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
313c0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
313d0 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c  ation {H18210} <
313e0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20400>.** EXPER
313f0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
31400 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64  is routine is id
31410 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b  entical to the [
31420 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
31430 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c  odule()] method,
31440 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
31450 69 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20  it has an extra 
31460 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65  parameter to spe
31470 63 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72  cify .** a destr
31480 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66  uctor function f
31490 6f 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61  or the client da
314a0 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c  ta pointer.  SQL
314b0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f  ite will.** invo
314c0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
314d0 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69  r function (if i
314e0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77  t is not NULL) w
314f0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f  hen SQLite.** no
31500 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68   longer needs th
31510 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f  e pClientData po
31520 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49  inter.  .*/.SQLI
31530 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
31540 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31550 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
31560 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
31570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
31580 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
31590 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
315a0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
315b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
315c0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
315d0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
315e0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
315f0 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
31600 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
31610 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
31620 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20  d *pClientData, 
31630 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
31640 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
31650 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
31660 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
31670 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
31680 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
31690 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
316a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
316b0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
316c0 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b  nstance Object {
316d0 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e  H18010} <S20400>
316e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
316f0 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58  lite3_vtab.** EX
31700 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
31710 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
31720 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
31730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
31740 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20  s a subclass.** 
31750 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
31760 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65   structure to de
31770 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
31780 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
31790 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
317a0 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
317b0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
317c0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
317d0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
317e0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
317f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
31800 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
31810 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
31820 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
31830 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
31840 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
31850 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
31860 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
31870 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
31880 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20  les methods can 
31890 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  set an error mes
318a0 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e  sage by assignin
318b0 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62  g a.** string ob
318c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
318d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
318e0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
318f0 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
31900 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
31910 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
31920 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
31930 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31940 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f  _free()].** prio
31950 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61  r to assigning a
31960 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a   new string to z
31970 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74  ErrMsg.  After t
31980 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
31990 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
319a0 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
319b0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
319c0 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
319d0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
319e0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
319f0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
31a00 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
31a10 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
31a20 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
31a30 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
31a40 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
31a50 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
31a60 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
31a70 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
31a80 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
31a90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31aa0 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47        /* NO LONG
31ab0 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61  ER USED */.  cha
31ac0 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
31ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31ae0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
31af0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
31b00 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
31b10 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
31b20 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
31b30 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
31b40 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
31b50 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
31b60 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
31b70 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
31b80 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32  ct  {H18020} <S2
31b90 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
31ba0 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
31bb0 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
31bc0 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
31bd0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
31be0 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
31bf0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
31c00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31c10 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
31c20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
31c30 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
31c40 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
31c50 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
31c60 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
31c70 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
31c80 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
31c90 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
31ca0 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
31cb0 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
31cc0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
31cd0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
31ce0 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
31cf0 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
31d00 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
31d10 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
31d20 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
31d30 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
31d40 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20  ethod.  Cussors 
31d50 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
31d60 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
31d70 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
31d80 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
31d90 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
31da0 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
31db0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
31dc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
31dd0 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
31de0 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
31df0 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
31e00 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
31e10 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
31e20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
31e30 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
31e40 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
31e50 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
31e60 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
31e70 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
31e80 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
31e90 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31ea0 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
31eb0 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
31ec0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
31ed0 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
31ee0 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
31ef0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
31f00 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
31f10 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
31f20 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
31f30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31f40 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
31f50 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
31f60 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30  al Table {H18280
31f70 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
31f80 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
31f90 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61   The [xCreate] a
31fa0 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
31fb0 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76  thods of a.** [v
31fc0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31fd0 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69  ule] call this i
31fe0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64  nterface.** to d
31ff0 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
32000 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
32010 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
32020 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
32030 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
32040 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
32050 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
32060 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
32070 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
32080 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
32090 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
320a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
320b0 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
320c0 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
320d0 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30  ual Table {H1830
320e0 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45  0} <S20400>.** E
320f0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
32100 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
32110 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
32120 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
32130 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
32140 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
32150 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
32160 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
32170 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
32180 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
32190 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
321a0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
321b0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
321c0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
321d0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  e overloaded..**
321e0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b  .** This API mak
321f0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
32200 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
32210 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
32220 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
32230 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
32240 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
32250 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
32260 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
32270 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
32280 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
32290 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
322a0 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  eated.  The impl
322b0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
322c0 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
322d0 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
322e0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
322f0 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
32300 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
32310 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
32320 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
32330 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
32340 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
32350 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64  o be a placehold
32360 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  er function that
32370 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64   can be overload
32380 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74  ed.** by a [virt
32390 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53  ual table]..*/.S
323a0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
323b0 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  AL int sqlite3_o
323c0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
323d0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
323e0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
323f0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
32400 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
32410 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
32420 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
32430 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
32440 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
32450 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
32460 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
32470 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
32480 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
32490 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
324a0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
324b0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
324c0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
324d0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
324e0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
324f0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
32500 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
32510 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
32520 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
32530 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
32540 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
32550 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
32560 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
32570 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
32580 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
32590 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
325a0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a  this comment..**
325b0 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
325c0 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
325d0 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
325e0 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
325f0 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ******.*/../*.**
32600 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
32610 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
32620 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33  LOB {H17800} <S3
32630 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0230>.** KEYWORD
32640 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d  S: {BLOB handle}
32650 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a   {BLOB handles}.
32660 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
32670 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
32680 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
32690 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63  pen BLOB on whic
326a0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  h.** [sqlite3_bl
326b0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
326c0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
326d0 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
326e0 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20  ..** Objects of 
326f0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
32700 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
32710 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
32720 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
32730 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
32740 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68  _close()]..** Th
32750 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
32760 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
32770 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
32780 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
32790 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
327a0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d  read or write sm
327b0 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20  all subsections 
327c0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20  of the BLOB..** 
327d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
327e0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
327f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
32800 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
32810 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  B in bytes..*/.t
32820 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
32830 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
32840 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
32850 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
32860 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
32870 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31  ental I/O {H1781
32880 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
32890 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
328a0 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20  s opens a [BLOB 
328b0 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d  handle | handle]
328c0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63   to the BLOB loc
328d0 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
328e0 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
328f0 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
32900 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
32910 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
32920 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42  ords, the same B
32930 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62  LOB that would b
32940 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
32950 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
32960 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
32970 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
32980 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d   WHERE [rowid] =
32990 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
329a0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
329b0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
329c0 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
329d0 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   then the BLOB i
329e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
329f0 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61  d.** and write a
32a00 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20  ccess. If it is 
32a10 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
32a20 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
32a30 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 49 74 20  d access..** It 
32a40 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
32a50 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
32a60 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
32a70 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69   an index or pri
32a80 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72  mary .** key for
32a90 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66   writing. ^If [f
32aa0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
32ab0 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62  raints] are enab
32ac0 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e  led, it is .** n
32ad0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
32ae0 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
32af0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b  t is part of a [
32b00 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77  child key] for w
32b10 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  riting..**.** No
32b20 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61  te that the data
32b30 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74  base name is not
32b40 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68   the filename th
32b50 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  at contains.** t
32b60 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20  he database but 
32b70 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f  rather the symbo
32b80 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  lic name of the 
32b90 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a  database that.**
32ba0 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 65   is assigned whe
32bb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
32bc0 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e  s connected usin
32bd0 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46  g [ATTACH]..** F
32be0 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
32bf0 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64  base file, the d
32c00 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
32c10 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54  "main"..** For T
32c20 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20  EMP tables, the 
32c30 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
32c40 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f   "temp"..**.** O
32c50 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
32c60 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
32c70 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b  ed and the new [
32c80 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20  BLOB handle] is 
32c90 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
32ca0 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65  pBlob. Otherwise
32cb0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
32cc0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
32cd0 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a   *ppBlob is set.
32ce0 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20  ** to be a null 
32cf0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 73  pointer..** This
32d00 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
32d10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
32d20 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
32d30 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
32d40 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
32d50 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
32d60 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
32d70 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
32d80 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
32d90 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68 61  tions.  Note tha
32da0 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
32db0 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
32dc0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
32dd0 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
32de0 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
32df0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
32e00 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
32e10 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
32e20 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
32e30 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
32e40 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
32e50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f  .**.** If the ro
32e60 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
32e70 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
32e80 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
32e90 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
32ea0 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
32eb0 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
32ec0 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
32ed0 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
32ee0 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
32ef0 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
32f00 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
32f10 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
32f20 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
32f30 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
32f40 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
32f50 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
32f60 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a  e is open on..**
32f70 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
32f80 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
32f90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
32fa0 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a  b_write()] for.*
32fb0 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42  * a expired BLOB
32fc0 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74   handle fail wit
32fd0 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65  h an return code
32fe0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
32ff0 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77  T]..** Changes w
33000 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c  ritten into a BL
33010 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  OB prior to the 
33020 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72  BLOB expiring ar
33030 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63  e not.** rollbac
33040 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74  k by the expirat
33050 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ion of the BLOB.
33060 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77    Such changes w
33070 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  ill eventually.*
33080 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20  * commit if the 
33090 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
330a0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
330b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 74  ion..**.** Use t
330c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
330d0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
330e0 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
330f0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
33100 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
33110 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20    The size of a 
33120 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
33130 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
33140 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
33150 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
33160 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
33170 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
33180 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
33190 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
331a0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d  bind_zeroblob()]
331b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
331c0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d  sult_zeroblob()]
331d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
331e0 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  nd the built-in 
331f0 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66  [zeroblob] SQL f
33200 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75  unction can be u
33210 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c  sed, if desired,
33220 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e  .** to create an
33230 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c   empty, zero-fil
33240 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63  led blob in whic
33250 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  h to read or wri
33260 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73  te using.** this
33270 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
33280 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73  * To avoid a res
33290 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72  ource leak, ever
332a0 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  y open [BLOB han
332b0 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e  dle] should even
332c0 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c  tually.** be rel
332d0 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20  eased by a call 
332e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
332f0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
33300 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
33310 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 38  * [H17813] [H178
33320 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 31  14] [H17816] [H1
33330 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b  7819] [H17821] [
33340 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H17824].*/.int s
33350 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
33360 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
33370 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
33380 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33390 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
333a0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
333b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
333c0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
333d0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
333e0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
333f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
33400 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
33410 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 33   {H17830} <S3023
33420 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20  0>.**.** Closes 
33430 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  an open [BLOB ha
33440 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f  ndle]..**.** Clo
33450 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
33460 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
33470 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
33480 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
33490 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
334a0 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
334b0 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
334c0 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
334d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
334e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b  nnection is in [
334f0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d  autocommit mode]
33500 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74  ..** If any writ
33510 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
33520 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
33530 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
33540 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
33550 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
33560 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
33570 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69  fit..**.** Closi
33580 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65  ng the BLOB ofte
33590 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61  n forces the cha
335a0 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64  nges.** out to d
335b0 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e  isk and so if an
335c0 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63  y I/O errors occ
335d0 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69  ur, they will li
335e0 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74  kely occur.** at
335f0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74   the time when t
33600 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
33610 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74  d.  Any errors t
33620 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67  hat occur during
33630 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20  .** closing are 
33640 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f  reported as a no
33650 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61  n-zero return va
33660 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42  lue..**.** The B
33670 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e  LOB is closed un
33680 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20  conditionally.  
33690 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75  Even if this rou
336a0 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  tine returns.** 
336b0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74  an error code, t
336c0 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c  he BLOB is still
336d0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 43   closed..**.** C
336e0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
336f0 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20  ine with a null 
33700 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20 61  pointer (which a
33710 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72  s would be retur
33720 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65 64  ned.** by failed
33730 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33740 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
33750 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33760 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  -op..**.** Requi
33770 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
33780 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48  833] [H17836] [H
33790 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17839].*/.int sq
337a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
337b0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
337c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
337d0 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69  F: Return The Si
337e0 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c  ze Of An Open BL
337f0 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30  OB {H17840} <S30
33800 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  230>.**.** Retur
33810 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62  ns the size in b
33820 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
33830 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
33840 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66  the .** successf
33850 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f  ully opened [BLO
33860 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73  B handle] in its
33870 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
33880 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e   The.** incremen
33890 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75  tal blob I/O rou
338a0 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72  tines can only r
338b0 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69  ead or overwriti
338c0 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62  ng existing.** b
338d0 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65  lob content; the
338e0 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  y cannot change 
338f0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
33900 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ob..**.** This r
33910 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
33920 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
33930 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
33940 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
33950 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
33960 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
33970 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
33980 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
33990 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
339a0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
339b0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
339c0 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
339d0 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
339e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
339f0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
33a00 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
33a10 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
33a20 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52 65  havior..**.** Re
33a30 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
33a40 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20 73  H17843].*/.int s
33a50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
33a60 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
33a70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33a80 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72  EF: Read Data Fr
33a90 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
33aa0 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d  entally {H17850}
33ab0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
33ac0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
33ad0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61   used to read da
33ae0 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20  ta from an open 
33af0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
33b00 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  to a.** caller-s
33b10 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
33b20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
33b30 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
33b40 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d  buffer Z.** from
33b50 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
33b60 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
33b70 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
33b80 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
33b90 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
33ba0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
33bb0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
33bc0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
33bd0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
33be0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
33bf0 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69  read.  If N or i
33c00 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73  Offset is.** les
33c10 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51  s than zero, [SQ
33c20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
33c30 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
33c40 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20  ata is read..** 
33c50 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
33c60 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
33c70 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
33c80 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
33c90 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
33ca0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
33cb0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
33cc0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
33cd0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70  .**.** An attemp
33ce0 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61  t to read from a
33cf0 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
33d00 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
33d10 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
33d20 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
33d30 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  BORT]..**.** On 
33d40 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f  success, SQLITE_
33d50 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
33d60 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
33d70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
33d80 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
33d90 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
33da0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
33db0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
33dc0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
33dd0 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
33de0 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
33df0 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
33e00 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
33e10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
33e20 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
33e30 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
33e40 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
33e50 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
33e60 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
33e70 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
33e80 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
33e90 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
33ea0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
33eb0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
33ec0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
33ed0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
33ee0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
33ef0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
33f00 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 35  ments:.** [H1785
33f10 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 37  3] [H17856] [H17
33f20 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 48  859] [H17862] [H
33f30 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d 20  17863] [H17865] 
33f40 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74 20  [H17868].*/.int 
33f50 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33f60 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  d(sqlite3_blob *
33f70 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e  , void *Z, int N
33f80 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
33f90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33fa0 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
33fb0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
33fc0 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c  tally {H17870} <
33fd0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30230>.**.** Th
33fe0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
33ff0 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
34000 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
34010 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
34020 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
34030 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
34040 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
34050 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
34060 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69  he buffer Z.** i
34070 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  nto the open BLO
34080 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
34090 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
340a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f  *.** If the [BLO
340b0 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
340c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
340d0 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
340e0 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
340f0 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
34100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
34110 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
34120 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
34130 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
34140 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
34150 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
34160 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
34170 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
34180 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
34190 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a  e BLOB; it is.**
341a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
341b0 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
341c0 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69  ze of a BLOB usi
341d0 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20  ng this API..** 
341e0 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
341f0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
34200 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
34210 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
34220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
34230 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
34240 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
34250 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a  itten.  If N is.
34260 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
34270 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
34280 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
34290 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
342a0 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65  ten..** The size
342b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e   of the BLOB (an
342c0 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
342d0 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
342e0 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
342f0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
34300 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
34310 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
34320 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41  terface..**.** A
34330 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69  n attempt to wri
34340 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64  te to an expired
34350 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
34360 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
34370 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
34380 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57  QLITE_ABORT].  W
34390 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f  rites to the BLO
343a0 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a  B that occurred.
343b0 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42  ** before the [B
343c0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69  LOB handle] expi
343d0 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c  red are not roll
343e0 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a  ed back by the.*
343f0 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  * expiration of 
34400 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75  the handle, thou
34410 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f  gh of course tho
34420 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74  se changes might
34430 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76  .** have been ov
34440 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
34450 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
34460 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42  expired the BLOB
34470 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79   handle.** or by
34480 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65   other independe
34490 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  nt statements..*
344a0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
344b0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
344c0 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  turned..** Other
344d0 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
344e0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
344f0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
34500 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
34510 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
34520 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
34530 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
34540 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
34550 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
34560 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
34570 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34580 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
34590 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
345a0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
345b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
345c0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
345d0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
345e0 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
345f0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
34600 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
34610 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
34620 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
34630 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  or..**.** See al
34640 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  so: [sqlite3_blo
34650 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  b_read()]..**.**
34660 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
34670 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37 38  * [H17873] [H178
34680 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48 31  74] [H17875] [H1
34690 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20 5b  7876] [H17877] [
346a0 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32 5d  H17879] [H17882]
346b0 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 31   [H17885].** [H1
346c0 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7888].*/.int sql
346d0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
346e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
346f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
34700 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
34710 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34720 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c  REF: Virtual Fil
34730 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73  e System Objects
34740 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31 30   {H11200} <S2010
34750 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  0>.**.** A virtu
34760 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
34770 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
34780 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
34790 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
347a0 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
347b0 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
347c0 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
347d0 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
347e0 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
347f0 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
34800 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
34810 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
34820 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
34830 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
34840 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
34850 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
34860 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
34870 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
34880 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
34890 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
348a0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
348b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
348c0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
348d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
348e0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
348f0 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e  n its name..** N
34900 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65  ames are case se
34910 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65  nsitive..** Name
34920 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
34930 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
34940 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ngs..** If there
34950 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20   is no match, a 
34960 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
34970 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
34980 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c  zVfsName is NULL
34990 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
349a0 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  t VFS is returne
349b0 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
349c0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
349d0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
349e0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a  fs_register()..*
349f0 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20 62  * Each new VFS b
34a00 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
34a10 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
34a20 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
34a30 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20  et..** The same 
34a40 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
34a50 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
34a60 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
34a70 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20  ury..** To make 
34a80 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
34a90 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
34aa0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
34ab0 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
34ac0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34ad0 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
34ae0 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
34af0 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
34b00 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
34b10 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
34b20 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
34b30 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
34b40 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
34b50 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
34b60 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
34b70 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
34b80 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
34b90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34ba0 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46   Unregister a VF
34bb0 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
34bc0 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
34bd0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
34be0 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74  * If the default
34bf0 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74   VFS is unregist
34c00 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46  ered, another VF
34c10 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a  S is chosen as.*
34c20 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20  * the default.  
34c30 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74  The choice for t
34c40 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72  he new VFS is ar
34c50 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52  bitrary..**.** R
34c60 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
34c70 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30 36  [H11203] [H11206
34c80 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31 32  ] [H11209] [H112
34c90 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48 31  12] [H11215] [H1
34ca0 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  1218].*/.sqlite3
34cb0 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
34cc0 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
34cd0 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
34ce0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
34cf0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
34d00 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
34d10 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
34d20 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
34d30 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
34d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34d50 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d 20  utexes {H17000} 
34d60 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
34d70 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
34d80 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
34d90 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
34da0 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
34db0 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72  . Though they ar
34dc0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69  e intended for i
34dd0 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
34de0 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74  y SQLite, code t
34df0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
34e00 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70  t SQLite is.** p
34e10 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20  ermitted to use 
34e20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34e30 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
34e40 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
34e50 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c  ode contains mul
34e60 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
34e70 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73  tions.** of thes
34e80 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
34e90 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74  .  An appropriat
34ea0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34eb0 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20  .** is selected 
34ec0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74  automatically at
34ed0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20   compile-time.  
34ee0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
34ef0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34f00 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
34f10 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
34f20 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
34f30 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
34f40 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
34f50 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
34f60 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
34f70 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
34f80 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
34f90 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
34fa0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
34fb0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e  e SQLITE_MUTEX_N
34fc0 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  OOP implementati
34fd0 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72  on is a set of r
34fe0 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20  outines.** that 
34ff0 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63  does no real loc
35000 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72  king and is appr
35010 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
35020 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74  in.** a single-t
35030 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
35040 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ion.  The SQLITE
35050 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53  _MUTEX_OS2,.** S
35060 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
35070 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f  EAD, and SQLITE_
35080 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d  MUTEX_W32 implem
35090 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
350a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
350b0 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e   use on OS/2, Un
350c0 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e  ix, and Windows.
350d0 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  .**.** If SQLite
350e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
350f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  h the SQLITE_MUT
35100 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f  EX_APPDEF prepro
35110 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20  cessor.** macro 
35120 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d  defined (with "-
35130 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
35140 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e  PDEF=1"), then n
35150 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  o mutex.** imple
35160 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63  mentation is inc
35170 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c  luded with the l
35180 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20  ibrary. In this 
35190 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c  case the.** appl
351a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
351b0 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74  ply a custom mut
351c0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
351d0 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  n using the.** [
351e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
351f0 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74  TEX] option of t
35200 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
35210 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  g() function.** 
35220 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73  before calling s
35230 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
35240 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72  e() or any other
35250 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
35260 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
35270 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  t calls sqlite3_
35280 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
35290 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 65  .** {H17011} The
352a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
352b0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
352c0 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
352d0 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
352e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
352f0 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 66   it. {H17012} If
35300 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
35310 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74  .** that means t
35320 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c  hat a mutex coul
35330 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74  d not be allocat
35340 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 4c  ed. {H17013} SQL
35350 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69  ite.** will unwi
35360 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64  nd its stack and
35370 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
35380 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20 61  . {H17014} The a
35390 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
353a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
353b0 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  c() is one of th
353c0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
353d0 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tants:.**.** <ul
353e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
353f0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
35400 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35410 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
35420 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35430 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
35440 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35450 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
35460 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  M.** <li>  SQLIT
35470 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
35480 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  EM2.** <li>  SQL
35490 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
354a0 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _PRNG.** <li>  S
354b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
354c0 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20  IC_LRU.** <li>  
354d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
354e0 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c  TIC_LRU2.** </ul
354f0 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d  >.**.** {H17015}
35500 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63   The first two c
35510 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73  onstants cause s
35520 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
35530 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a  oc() to create.*
35540 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20  * a new mutex.  
35550 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
35560 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
35570 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
35580 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
35590 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
355a0 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
355b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
355c0 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a  is used. {END}.*
355d0 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
355e0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
355f0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
35600 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
35610 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
35620 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35630 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
35640 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
35650 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
35660 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74 20  .  {H17016} But 
35670 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
35680 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72   request a recur
35690 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a  sive mutex in.**
356a0 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20   cases where it 
356b0 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65  really needs one
356c0 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61  .  {END} If a fa
356d0 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69  ster non-recursi
356e0 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  ve mutex.** impl
356f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76  ementation is av
35700 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68  ailable on the h
35710 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68  ost platform, th
35720 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65  e mutex subsyste
35730 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72  m.** might retur
35740 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69  n such a mutex i
35750 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51  n response to SQ
35760 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e  LITE_MUTEX_FAST.
35770 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20  .**.** {H17017} 
35780 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65  The other allowe
35790 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  d parameters to 
357a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
357b0 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72  loc() each retur
357c0 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
357d0 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
357e0 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45  isting mutex. {E
357f0 4e 44 7d 20 20 53 69 78 20 73 74 61 74 69 63 20  ND}  Six static 
35800 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75  mutexes are.** u
35810 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65  sed by the curre
35820 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  nt version of SQ
35830 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65  Lite.  Future ve
35840 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
35850 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69  .** may add addi
35860 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
35870 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d  texes.  Static m
35880 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69  utexes are for i
35890 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
358a0 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20  y SQLite only.  
358b0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
358c0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74  t use SQLite mut
358d0 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75  exes should.** u
358e0 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61  se only the dyna
358f0 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75  mic mutexes retu
35900 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d  rned by SQLITE_M
35910 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20  UTEX_FAST or.** 
35920 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
35930 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  URSIVE..**.** {H
35940 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74  17018} Note that
35950 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
35960 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
35970 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
35980 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
35990 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
359a0 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
359b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
359c0 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
359d0 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
359e0 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
359f0 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34  y call.  {H17034
35a00 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74  } But for the st
35a10 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79  atic.** mutex ty
35a20 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75  pes, the same mu
35a30 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20  tex is returned 
35a40 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68  on every call th
35a50 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61  at has.** the sa
35a60 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a  me type number..
35a70 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54  **.** {H17019} T
35a80 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
35a90 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
35aa0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
35ab0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
35ac0 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
35ad0 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 53 51  tex. {H17020} SQ
35ae0 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20  Lite is careful 
35af0 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76  to deallocate ev
35b00 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  ery.** dynamic m
35b10 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c  utex that it all
35b20 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31 7d  ocates. {A17021}
35b30 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   The dynamic mut
35b40 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65  exes must not be
35b50 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20   in.** use when 
35b60 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63  they are dealloc
35b70 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20 41  ated. {A17022} A
35b80 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61  ttempting to dea
35b90 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63  llocate a static
35ba0 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74  .** mutex result
35bb0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
35bc0 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 32 33  ehavior. {H17023
35bd0 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64  } SQLite never d
35be0 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20  eallocates.** a 
35bf0 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45  static mutex. {E
35c00 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ND}.**.** The sq
35c10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
35c20 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
35c30 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
35c40 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
35c50 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
35c60 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20 61 6e  . {H17024} If an
35c70 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20  other thread is 
35c80 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74  already within t
35c90 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c  he mutex,.** sql
35ca0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35cb0 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e  () will block an
35cc0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
35cd0 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72  try() will retur
35ce0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  n.** SQLITE_BUSY
35cf0 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68 65 20  . {H17025}  The 
35d00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
35d10 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
35d20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
35d30 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
35d40 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31  sful entry.  {H1
35d50 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72  7026} Mutexes cr
35d60 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53  eated using.** S
35d70 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35d80 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74  RSIVE can be ent
35d90 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
35da0 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20  mes by the same 
35db0 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30  thread..** {H170
35dc0 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65  27} In such case
35dd0 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
35de0 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
35df0 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
35e00 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
35e10 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
35e20 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31   can enter.  {A1
35e30 37 30 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d  7028} If the sam
35e40 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74  e thread tries t
35e50 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65  o enter any othe
35e60 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74  r.** kind of mut
35e70 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ex more than onc
35e80 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  e, the behavior 
35e90 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
35ea0 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 74 65   {H17029} SQLite
35eb0 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
35ec0 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
35ed0 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
35ee0 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a  use of mutexes..
35ef0 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65  **.** Some syste
35f00 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ms (for example,
35f10 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20   Windows 95) do 
35f20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20  not support the 
35f30 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70  operation.** imp
35f40 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69  lemented by sqli
35f50 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e  te3_mutex_try().
35f60 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65    On those syste
35f70 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ms, sqlite3_mute
35f80 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20  x_try().** will 
35f90 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51  always return SQ
35fa0 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 31 37  LITE_BUSY.  {H17
35fb0 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20  030} The SQLite 
35fc0 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75  core only ever u
35fd0 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ses.** sqlite3_m
35fe0 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e  utex_try() as an
35ff0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f   optimization so
36000 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61   this is accepta
36010 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
36020 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 68 65  .** {H17031} The
36030 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
36040 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65  eave() routine e
36050 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61  xits a mutex tha
36060 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  t was.** previou
36070 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  sly entered by t
36080 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20  he same thread. 
36090 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62 65   {A17032} The be
360a0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
360b0 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75  efined if the mu
360c0 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65  tex is not curre
360d0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  ntly entered by 
360e0 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74  the.** calling t
360f0 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20  hread or is not 
36100 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
36110 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d 20 53  ted.  {H17033} S
36120 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
36130 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b  ver do either. {
36140 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  END}.**.** If th
36150 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
36160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
36170 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  r(), sqlite3_mut
36180 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20  ex_try(), or.** 
36190 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
361a0 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  ave() is a NULL 
361b0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c  pointer, then al
361c0 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  l three routines
361d0 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f  .** behave as no
361e0 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  -ops..**.** See 
361f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
36200 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
36210 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36220 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
36230 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
36240 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
36250 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
36260 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
36270 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36280 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
36290 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
362a0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
362b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
362c0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
362d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
362e0 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
362f0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
36300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
36310 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  ex Methods Objec
36320 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31  t {H17120} <S201
36330 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  30>.** EXPERIMEN
36340 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  TAL.**.** An ins
36350 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
36360 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20  ructure defines 
36370 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f  the low-level ro
36380 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74  utines.** used t
36390 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75  o allocate and u
363a0 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a  se mutexes..**.*
363b0 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64  * Usually, the d
363c0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70  efault mutex imp
363d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f  lementations pro
363e0 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  vided by SQLite 
363f0 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e  are.** sufficien
36400 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75  t, however the u
36410 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69  ser has the opti
36420 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69  on of substituti
36430 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69  ng a custom.** i
36440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
36450 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65  r specialized de
36460 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73  ployments or sys
36470 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53  tems for which S
36480 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
36490 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74  t provide a suit
364a0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
364b0 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ion. In this cas
364c0 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63  e, the user.** c
364d0 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c  reates and popul
364e0 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65  ates an instance
364f0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
36500 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f  re to pass.** to
36510 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
36520 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65  ) along with the
36530 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
36540 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
36550 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20  * Additionally, 
36560 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
36570 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61  his structure ca
36580 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a  n be used as an.
36590 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62  ** output variab
365a0 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67  le when querying
365b0 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20   the system for 
365c0 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65  the current mute
365d0 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
365e0 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b  ion, using the [
365f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
36600 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  TMUTEX] option..
36610 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78  **.** The xMutex
36620 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69  Init method defi
36630 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
36640 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
36650 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
36660 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61  ystem initializa
36670 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69  tion by the sqli
36680 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
36690 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48   function..** {H
366a0 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65  17001} The xMute
366b0 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68  xInit routine sh
366c0 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79  all be called by
366d0 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72   SQLite once for
366e0 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69   each.** effecti
366f0 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ve call to [sqli
36700 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
36710 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75  ]..**.** The xMu
36720 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65  texEnd method de
36730 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
36740 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
36750 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
36760 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e   system shutdown
36770 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36780 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74  shutdown() funct
36790 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c  ion. The.** impl
367a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
367b0 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70  is method is exp
367c0 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65  ected to release
367d0 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67   all outstanding
367e0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62  .** resources ob
367f0 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75  tained by the mu
36800 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c  tex methods impl
36810 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65  ementation, espe
36820 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20  cially.** those 
36830 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
36840 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
36850 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20  d. {H17003} The 
36860 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69  xMutexEnd().** i
36870 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
36880 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  e invoked once f
36890 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  or each call to 
368a0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
368b0 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  n()]..**.** The 
368c0 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20  remaining seven 
368d0 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20  methods defined 
368e0 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
368f0 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a  e (xMutexAlloc,.
36900 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78  ** xMutexFree, x
36910 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74  MutexEnter, xMut
36920 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61  exTry, xMutexLea
36930 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61  ve, xMutexHeld a
36940 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68  nd.** xMutexNoth
36950 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74  eld) implement t
36960 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74  he following int
36970 65 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74  erfaces (respect
36980 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ively):.**.** <u
36990 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  l>.**   <li>  [s
369a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
369b0 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  oc()] </li>.**  
369c0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
369d0 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f  mutex_free()] </
369e0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
369f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
36a00 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ter()] </li>.** 
36a10 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
36a20 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f  _mutex_try()] </
36a30 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
36a40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
36a50 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ave()] </li>.** 
36a60 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
36a70 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c  _mutex_held()] <
36a80 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
36a90 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e  [sqlite3_mutex_n
36aa0 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  otheld()] </li>.
36ab0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
36ac0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
36ad0 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70  ce is that the p
36ae0 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58  ublic sqlite3_XX
36af0 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d  X functions enum
36b00 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20  erated.** above 
36b10 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
36b20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  any invocations 
36b30 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c  that pass a NULL
36b40 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
36b50 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  .** of a valid m
36b60 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65  utex handle. The
36b70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36b80 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20   of the methods 
36b90 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  defined.** by th
36ba0 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65  is structure are
36bb0 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
36bc0 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73   handle this cas
36bd0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a  e, the results.*
36be0 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e  * of passing a N
36bf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
36c00 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  ead of a valid m
36c10 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20  utex handle are 
36c20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e  undefined.** (i.
36c30 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61  e. it is accepta
36c40 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61  ble to provide a
36c50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36c60 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20   that segfaults 
36c70 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73  if.** it is pass
36c80 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ed a NULL pointe
36c90 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  r)..**.** The xM
36ca0 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f  utexInit() metho
36cb0 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  d must be thread
36cc0 73 61 66 65 2e 20 20 49 74 20 6d 75 73 74 20 62  safe.  It must b
36cd0 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a  e harmless to.**
36ce0 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e   invoke xMutexIn
36cf0 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d  it() mutiple tim
36d00 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
36d10 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77  me process and w
36d20 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76  ithout.** interv
36d30 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78  ening calls to x
36d40 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63  MutexEnd().  Sec
36d50 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
36d60 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78  nt calls to.** x
36d70 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
36d80 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
36d90 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  * xMutexInit() m
36da0 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
36db0 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te memory alloca
36dc0 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d  tion ([sqlite3_m
36dd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20  alloc()].** and 
36de0 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e  its associates).
36df0 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75    Similarly, xMu
36e00 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
36e10 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
36e20 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
36e30 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
36e40 20 6d 75 74 65 78 2e 20 20 48 6f 77 65 76 65 72   mutex.  However
36e50 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d   xMutexAlloc() m
36e60 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a  ay use SQLite.**
36e70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36e80 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72  on for a fast or
36e90 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
36ea0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
36eb0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78  ill invoke the x
36ec0 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f  MutexEnd() metho
36ed0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
36ee0 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a  shutdown()] is.*
36ef0 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e  * called, but on
36f00 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20  ly if the prior 
36f10 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e  call to xMutexIn
36f20 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  it returned SQLI
36f30 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75  TE_OK..** If xMu
36f40 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e  texInit fails in
36f50 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20   any way, it is 
36f60 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61  expected to clea
36f70 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c  n up after itsel
36f80 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65  f.** prior to re
36f90 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65  turning..*/.type
36fa0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
36fb0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
36fc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
36fd0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
36fe0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
36ff0 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78  hods {.  int (*x
37000 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29  MutexInit)(void)
37010 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37020 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71  End)(void);.  sq
37030 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78  lite3_mutex *(*x
37040 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29  MutexAlloc)(int)
37050 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
37060 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d  xFree)(sqlite3_m
37070 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
37080 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73  (*xMutexEnter)(s
37090 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
370a0 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54  .  int (*xMutexT
370b0 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ry)(sqlite3_mute
370c0 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
370d0 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69  MutexLeave)(sqli
370e0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
370f0 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64  int (*xMutexHeld
37100 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37110 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37120 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74  exNotheld)(sqlit
37130 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a  e3_mutex *);.};.
37140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37150 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74   Mutex Verificat
37160 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
37170 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c  7080} <S20130> <
37180 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
37190 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
371a0 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74  held() and sqlit
371b0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
371c0 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  () routines.** a
371d0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
371e0 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72  use inside asser
371f0 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  t() statements. 
37200 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c  {H17081} The SQL
37210 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
37220 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
37230 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
37240 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
37250 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
37260 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
37270 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
37280 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
37290 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f   {H17082} The co
372a0 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
372b0 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
372c0 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
372d0 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
372e0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
372f0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
37300 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30  BUG flag.  {A170
37310 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74  87} External mut
37320 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
37330 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72  ns.** are only r
37340 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69  equired to provi
37350 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  de these routine
37360 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55  s if SQLITE_DEBU
37370 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20  G is.** defined 
37380 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73  and if NDEBUG is
37390 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a   not defined..**
373a0 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65  .** {H17083} The
373b0 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
373c0 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
373d0 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
373e0 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
373f0 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
37400 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
37410 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
37420 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
37430 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d   {X17084} The im
37440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
37450 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20  not required to 
37460 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e  provided version
37470 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f  s of these.** ro
37480 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75  utines that actu
37490 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68  ally work. If th
374a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
374b0 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64   does not provid
374c0 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72  e working.** ver
374d0 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72  sions of these r
374e0 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75  outines, it shou
374f0 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76  ld at least prov
37500 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61  ide stubs that a
37510 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20  lways.** return 
37520 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65  true so that one
37530 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70   does not get sp
37540 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e  urious assertion
37550 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a   failures..**.**
37560 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65   {H17085} If the
37570 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
37580 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
37590 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
375a0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
375b0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
375c0 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20  eturn 1.  {END} 
375d0 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74  This seems count
375e0 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e  er-intuitive sin
375f0 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68  ce.** clearly th
37600 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62  e mutex cannot b
37610 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65  e held if it doe
37620 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75  s not exist.  Bu
37630 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61  t the.** the rea
37640 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f  son the mutex do
37650 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20  es not exist is 
37660 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  because the buil
37670 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e  d is not.** usin
37680 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20  g mutexes.  And 
37690 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74  we do not want t
376a0 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74  he assert() cont
376b0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61  aining the.** ca
376c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ll to sqlite3_mu
376d0 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61  tex_held() to fa
376e0 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72  il, so a non-zer
376f0 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74  o return is.** t
37700 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  he appropriate t
37710 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31  hing to do.  {H1
37720 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65  7086} The sqlite
37730 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
37740 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
37750 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
37760 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
37770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
37780 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  /.int sqlite3_mu
37790 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33  tex_held(sqlite3
377a0 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
377b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
377c0 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
377d0 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
377e0 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65  3REF: Mutex Type
377f0 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30  s {H17001} <H170
37800 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
37810 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
37820 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  oc()] interface 
37830 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
37840 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68  rgument.** which
37850 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
37860 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
37870 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
37880 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65  t of static mute
37890 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66  xes may change f
378a0 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72  rom one SQLite r
378b0 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a  elease to the.**
378c0 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
378d0 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69  ions that overri
378e0 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  de the built-in 
378f0 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74  mutex logic must
37900 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20   be.** prepared 
37910 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61  to accommodate a
37920 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63  dditional static
37930 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65   mutexes..*/.#de
37940 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37950 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20  X_FAST          
37960 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
37970 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
37980 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  IVE        1.#de
37990 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
379a0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20  X_STATIC_MASTER 
379b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
379c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
379d0 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a  _MEM       3  /*
379e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
379f0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37a00 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37a10 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a  _MEM2      4  /*
37a20 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65   NOT USED */.#de
37a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37a40 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20  X_STATIC_OPEN   
37a50 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
37a60 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23  BtreeOpen() */.#
37a70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37a80 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20  TEX_STATIC_PRNG 
37a90 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
37aa0 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23  e3_random() */.#
37ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37ac0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20  TEX_STATIC_LRU  
37ad0 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70       6  /* lru p
37ae0 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66  age list */.#def
37af0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37b00 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20  _STATIC_LRU2    
37b10 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    7  /* lru page
37b20 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   list */../*.** 
37b30 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
37b40 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72  ve the mutex for
37b50 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
37b60 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20  ection {H17002} 
37b70 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H17000>.**.** T
37b80 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
37b90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
37ba0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
37bb0 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ex] object that 
37bc0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61  .** serializes a
37bd0 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61  ccess to the [da
37be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37bf0 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  n] given in the 
37c00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e  argument.** when
37c10 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
37c20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69  mode] is Seriali
37c30 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  zed..** If the [
37c40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
37c50 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  is Single-thread
37c60 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   or Multi-thread
37c70 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f   then this.** ro
37c80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
37c90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
37ca0 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
37cb0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
37cc0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
37cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77  ** CAPI3REF: Low
37ce0 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f  -Level Control O
37cf0 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  f Database Files
37d00 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30   {H11300} <S3080
37d10 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31  0>.**.** {H11301
37d20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
37d30 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
37d40 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
37d50 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20   direct call to 
37d60 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74  the.** xFileCont
37d70 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74  rol method for t
37d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
37d90 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
37da0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
37db0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
37dc0 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69  atabase identifi
37dd0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
37de0 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33   argument. {H113
37df0 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20  02} The.** name 
37e00 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37e10 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  is the name assi
37e20 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61  gned to the data
37e30 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c  base by the.** <
37e40 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74  a href="lang_att
37e50 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48  ach.html">ATTACH
37e60 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  </a> SQL command
37e70 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65   that opened the
37e80 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48  .** database. {H
37e90 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f  11303} To contro
37ea0 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  l the main datab
37eb0 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68  ase file, use th
37ec0 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a  e name "main".**
37ed0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
37ee0 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65  er. {H11304} The
37ef0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
37f00 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
37f10 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
37f20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63  are passed direc
37f30 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74  tly through to t
37f40 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
37f50 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ird parameters o
37f60 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f  f.** the xFileCo
37f70 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b  ntrol method.  {
37f80 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75  H11305} The retu
37f90 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
37fa0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20  xFileControl.** 
37fb0 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74  method becomes t
37fc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37fd0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
37fe0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20  .**.** {H11306} 
37ff0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
38000 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65  rameter (zDbName
38010 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  ) does not match
38020 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79   the name of any
38030 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73  .** open databas
38040 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c  e file, then SQL
38050 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74  ITE_ERROR is ret
38060 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20  urned. {H11307} 
38070 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f  This error.** co
38080 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62  de is not rememb
38090 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f  ered and will no
380a0 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79  t be recalled by
380b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
380c0 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  e()].** or [sqli
380d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b  te3_errmsg()]. {
380e0 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65  A11308} The unde
380f0 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74  rlying xFileCont
38100 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74  rol method might
38110 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  .** also return 
38120 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b  SQLITE_ERROR.  {
38130 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73  A11309} There is
38140 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69   no way to disti
38150 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a  nguish between.*
38160 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a  * an incorrect z
38170 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51  DbName and an SQ
38180 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72  LITE_ERROR retur
38190 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72  n from the under
381a0 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f  lying.** xFileCo
381b0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45  ntrol method. {E
381c0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ND}.**.** See al
381d0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  so: [SQLITE_FCNT
381e0 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a  L_LOCKSTATE].*/.
381f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  int sqlite3_file
38200 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33  _control(sqlite3
38210 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
38220 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20  DbName, int op, 
38230 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
38240 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67  API3REF: Testing
38250 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34   Interface {H114
38260 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a  00} <S30800>.**.
38270 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
38280 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e  est_control() in
38290 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
382a0 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65  to read out inte
382b0 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66  rnal.** state of
382c0 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69   SQLite and to i
382d0 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74  nject faults int
382e0 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73  o SQLite for tes
382f0 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73  ting.** purposes
38300 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
38310 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65  ameter is an ope
38320 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74  ration code that
38330 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74   determines.** t
38340 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69  he number, meani
38350 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f  ng, and operatio
38360 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75  n of all subsequ
38370 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  ent parameters..
38380 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
38390 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20  face is not for 
383a0 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69  use by applicati
383b0 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20  ons.  It exists 
383c0 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65  solely.** for ve
383d0 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72  rifying the corr
383e0 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  ect operation of
383f0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
38400 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a  ary.  Depending.
38410 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51  ** on how the SQ
38420 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20  Lite library is 
38430 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69  compiled, this i
38440 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e  nterface might n
38450 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  ot exist..**.** 
38460 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
38470 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64  he operation cod
38480 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e  es, their meanin
38490 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65  gs, the paramete
384a0 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c  rs.** they take,
384b0 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64   and what they d
384c0 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63  o are all subjec
384d0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
384e0 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55  out notice..** U
384f0 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68  nlike most of th
38500 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68  e SQLite API, th
38510 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  is function is n
38520 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
38530 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73  .** operate cons
38540 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e  istently from on
38550 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
38560 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71   next..*/.int sq
38570 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
38580 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  ol(int op, ...);
38590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
385a0 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66  : Testing Interf
385b0 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f  ace Operation Co
385c0 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31  des {H11410} <H1
385d0 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1400>.**.** Thes
385e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
385f0 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74  the valid operat
38600 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74  ion code paramet
38610 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74  ers used.** as t
38620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
38630 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65  t to [sqlite3_te
38640 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a  st_control()]..*
38650 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d  *.** These param
38660 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20  eters and their 
38670 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62  meanings are sub
38680 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a  ject to change.*
38690 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  * without notice
386a0 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20  .  These values 
386b0 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20  are for testing 
386c0 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a  purposes only..*
386d0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
386e0 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e  hould not use an
386f0 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  y of these param
38700 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20  eters or the.** 
38710 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f  [sqlite3_test_co
38720 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
38730 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
38740 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
38750 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20  RNG_SAVE        
38760 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
38770 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
38780 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20  L_PRNG_RESTORE  
38790 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
387a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
387b0 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20  CTRL_PRNG_RESET 
387c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
387d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
387e0 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54  ESTCTRL_BITVEC_T
387f0 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  EST             
38800 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
38810 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54  E_TESTCTRL_FAULT
38820 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20  _INSTALL        
38830 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
38840 4c 49 54 45 5f 54 45 53 54 43 54 5