/ Hex Artifact Content
Login

Artifact ef766c813d377a0f3f5e6131d0a2667ecd6301c1:


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 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7390: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
73a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
73b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4f 70 65 6e    int (*xShmOpen
73c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
73d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 53 69  ;.  int (*xShmSi
73e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
73f0: 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65 2c 20  *, int reqSize, 
7400: 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65 29 3b 0a  int *pNewSize);.
7410: 20 20 69 6e 74 20 28 2a 78 53 68 6d 47 65 74 29    int (*xShmGet)
7420: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7430: 69 6e 74 20 72 65 71 53 69 7a 65 2c 20 69 6e 74  int reqSize, int
7440: 20 2a 70 53 69 7a 65 2c 20 76 6f 69 64 20 76 6f   *pSize, void vo
7450: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
7460: 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29 28   (*xShmRelease)(
7470: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7480: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
7490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
74a0: 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b   int desiredLock
74b0: 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b  , int *gotLock);
74c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f  .  int (*xShmClo
74d0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
74e0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
74f0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
7500: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
7510: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
7520: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
7530: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
7540: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
7550: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
7560: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7570: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
7580: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
7590: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
75a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
75b0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
75c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
75d0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
75e0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
75f0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7600: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7610: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7620: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7630: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
7640: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
7650: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
7660: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
7670: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
7680: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
7690: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
76a0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
76b0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
76c0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
76d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
76e0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
76f0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7700: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7710: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7720: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7730: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7740: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
7750: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
7760: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
7770: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
7780: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
7790: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
77a0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
77b0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
77c0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
77d0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
77e0: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
77f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
7800: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
7810: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
7820: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
7830: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
7840: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
7850: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7860: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
7870: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
7880: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
7890: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
78a0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
78b0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
78c0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
78d0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
78e0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
78f0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
7900: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
7910: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
7920: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
7930: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
7940: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
7950: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
7960: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
7970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7980: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7990: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
79a0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
79b0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
79c0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
79d0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
79e0: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69  ILE      3.#defi
79f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
7a00: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
7a10: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
7a20: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7a30: 54 20 20 20 20 20 20 20 20 35 0a 0a 2f 2a 0a 2a  T        5../*.*
7a40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
7a50: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
7a60: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
7a70: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
7a80: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
7a90: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
7aa0: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
7ab0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
7ac0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
7ad0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
7ae0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
7af0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
7b00: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
7b10: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
7b20: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
7b30: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
7b40: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
7b50: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
7b60: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
7b70: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
7b80: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
7b90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7ba0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
7bb0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
7bc0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7bd0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7be0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
7bf0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
7c00: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
7c10: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
7c20: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
7c30: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
7c40: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
7c50: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
7c60: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
7c70: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
7c80: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
7c90: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
7ca0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
7cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
7cc0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
7cd0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
7ce0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
7cf0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
7d00: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
7d10: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
7d20: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
7d30: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
7d40: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
7d50: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
7d60: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
7d70: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
7d80: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
7d90: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
7da0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
7db0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
7dc0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
7dd0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
7de0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
7df0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
7e00: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
7e10: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
7e20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
7e30: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
7e40: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
7e50: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
7e60: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
7e70: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
7e80: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
7e90: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
7ea0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
7eb0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
7ec0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
7ed0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
7ee0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
7ef0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
7f00: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
7f10: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
7f20: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
7f30: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
7f40: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
7f50: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
7f60: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
7f70: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
7f80: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
7f90: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
7fa0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
7fb0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
7fc0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
7fd0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
7fe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
7ff0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
8000: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
8010: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
8020: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
8030: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
8040: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
8050: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
8060: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
8070: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
8080: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
8090: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
80a0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
80b0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
80c0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
80d0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
80e0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
80f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8100: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
8110: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
8120: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
8130: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
8140: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
8150: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
8160: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
8170: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
8180: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
8190: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
81a0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
81b0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
81c0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
81d0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
81e0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
81f0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8200: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
8210: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
8220: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
8230: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
8240: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
8250: 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65  hname().  SQLite
8260: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
8270: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
8280: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
8290: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
82a0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
82b0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
82c0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
82d0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
82e0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
82f0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
8300: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
8310: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
8320: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
8330: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
8340: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
8350: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
8360: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
8370: 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70  parameter is xOp
8380: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
8390: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
83a0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
83b0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
83c0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
83d0: 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68  le.  Whenever th
83e0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
83f0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
8400: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
8410: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
8420: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
8430: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
8440: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
8450: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
8460: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
8470: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
8480: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
8490: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
84a0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
84b0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
84c0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
84d0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
84e0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
84f0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
8500: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
8510: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
8520: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
8530: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
8540: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
8550: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
8560: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
8570: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
8580: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
8590: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
85a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
85b0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
85c0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
85d0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
85e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
85f0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
8600: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8610: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8620: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
8630: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
8640: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
8650: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
8660: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8670: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
8680: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8690: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
86a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
86b0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
86e0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
86f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
8700: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
8710: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
8720: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
8730: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8740: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
8750: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8760: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
8770: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
8780: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
8790: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
87a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
87b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
87c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
87d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
87e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
87f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
8800: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
8810: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
8820: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
8830: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
8840: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
8850: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
8860: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
8870: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
8880: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
8890: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
88a0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
88b0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
88c0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
88d0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
88e0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
88f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
8900: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
8910: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
8920: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
8930: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
8940: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
8950: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
8960: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
8970: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
8980: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
8990: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
89a0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
89b0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
89c0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
89d0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
89e0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
89f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
8a00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
8a10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
8a20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8a30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
8a40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
8a50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
8a60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
8a70: 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
8a80: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8a90: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
8aa0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61  set for TEMP  da
8ab0: 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c  tabases, journal
8ac0: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75  s and for subjou
8ad0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rnals..**.** The
8ae0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
8af0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
8b00: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
8b10: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
8b20: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
8b30: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
8b40: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
8b50: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
8b60: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
8b70: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
8b80: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
8b90: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
8ba0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
8bb0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
8bc0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
8bd0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
8be0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
8bf0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
8c00: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
8c10: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
8c20: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
8c30: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
8c40: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
8c50: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
8c60: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
8c70: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
8c80: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
8c90: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
8ca0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
8cb0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61  ss..**.** At lea
8cc0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
8cd0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
8ce0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
8cf0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
8d00: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
8d10: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
8d20: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
8d30: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
8d40: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
8d50: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
8d60: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
8d70: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
8d80: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
8d90: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
8da0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
8db0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
8dc0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
8dd0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
8de0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
8df0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
8e00: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8e10: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
8e20: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
8e30: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
8e40: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
8e50: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
8e60: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
8e70: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
8e80: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
8e90: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
8ea0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
8eb0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
8ec0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
8ed0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
8ee0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  all..**.** The f
8ef0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8f00: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
8f10: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
8f20: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
8f30: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
8f40: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
8f50: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8f60: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
8f70: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
8f80: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
8f90: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
8fa0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
8fb0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
8fc0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
8fd0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
8fe0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
8ff0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
9000: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
9010: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
9020: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
9030: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
9040: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
9050: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
9060: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
9070: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
9080: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
9090: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
90a0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
90b0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
90c0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
90d0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
90e0: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
90f0: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
9100: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
9110: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
9120: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
9130: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
9140: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
9150: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
9160: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
9170: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
9180: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
9190: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
91a0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
91b0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
91c0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
91d0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
91e0: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
91f0: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
9200: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
9210: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
9220: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
9230: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
9240: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
9250: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
9260: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
9270: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
9280: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
9290: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
92a0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
92b0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
92c0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
92d0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
92e0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
92f0: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
9300: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
9310: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
9320: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
9330: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
9340: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
9350: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
9360: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
9370: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
9380: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
9390: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
93a0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
93b0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
93c0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
93d0: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
93e0: 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65  me..**.*/.typede
93f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
9400: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
9410: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
9420: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
9430: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
9440: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
9450: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
9460: 75 72 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20  urrently 2) */. 
9470: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
9480: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
9490: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
94a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
94b0: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
94c0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
94d0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
94e0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
94f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
9500: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
9510: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
9520: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
9530: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
9540: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
9550: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
9560: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
9570: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
9580: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
9590: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
95a0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
95b0: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
95c0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
95d0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
95e0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
95f0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
9600: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
9610: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
9620: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
9630: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9640: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
9650: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
9660: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
9670: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9680: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
9690: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
96a0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
96b0: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
96c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
96d0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
96e0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
96f0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
9700: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
9710: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
9720: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
9730: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
9740: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9750: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
9760: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
9770: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
9780: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
9790: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
97a0: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
97b0: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
97c0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
97d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
97e0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
97f0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
9800: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
9810: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
9820: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
9830: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
9840: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
9850: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
9860: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
9870: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
9880: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
9890: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
98a0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
98b0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
98c0: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
98d0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
98e0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
98f0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
9900: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
9910: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
9920: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
9930: 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
9940: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9950: 73 74 20 63 68 61 72 20 2a 7a 4f 6c 64 2c 20 63  st char *zOld, c
9960: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 2c  onst char *zNew,
9970: 20 69 6e 74 20 64 69 72 53 79 6e 63 29 3b 0a 20   int dirSync);. 
9980: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
9990: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
99a0: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
99b0: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
99c0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
99d0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
99e0: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
99f0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
9a00: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
9a10: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
9a20: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
9a30: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
9a40: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
9a50: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
9a60: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
9a70: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
9a80: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
9a90: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9aa0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
9ab0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
9ac0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
9ad0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
9ae0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
9af0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
9b00: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
9b10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
9b20: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
9b30: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
9b40: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
9b50: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
9b60: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
9b70: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
9b80: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9b90: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
9ba0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
9bb0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
9bc0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
9bd0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
9be0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9bf0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
9c00: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
9c10: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9c20: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
9c30: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
9c40: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
9c50: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
9c60: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9c70: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
9c80: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
9c90: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
9ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9cb0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
9cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9cd0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
9ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9cf0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
9d00: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
9d10: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9d20: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
9d30: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
9d40: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
9d50: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
9d60: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 73  arious locking s
9d70: 74 61 74 65 73 20 74 68 61 74 0a 2a 2a 20 61 6e  tates that.** an
9d80: 20 73 71 6c 69 74 65 33 5f 73 68 6d 20 6f 62 6a   sqlite3_shm obj
9d90: 65 63 74 20 63 61 6e 20 62 65 20 69 6e 2e 0a 2a  ect can be in..*
9da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9db0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
9dc0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
9dd0: 54 45 5f 53 48 4d 5f 52 45 41 44 20 20 20 20 20  TE_SHM_READ     
9de0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
9df0: 4c 49 54 45 5f 53 48 4d 5f 52 45 41 44 5f 46 55  LITE_SHM_READ_FU
9e00: 4c 4c 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  LL    2.#define 
9e10: 53 51 4c 49 54 45 5f 53 48 4d 5f 57 52 49 54 45  SQLITE_SHM_WRITE
9e20: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
9e30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 50 45 4e  e SQLITE_SHM_PEN
9e40: 44 49 4e 47 20 20 20 20 20 20 34 0a 23 64 65 66  DING      4.#def
9e50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 43  ine SQLITE_SHM_C
9e60: 48 45 43 4b 50 4f 49 4e 54 20 20 20 35 0a 23 64  HECKPOINT   5.#d
9e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
9e80: 5f 52 45 43 4f 56 45 52 20 20 20 20 20 20 36 0a  _RECOVER      6.
9e90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9ea0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
9eb0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
9ec0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
9ed0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9ee0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
9ef0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
9f00: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
9f10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9f20: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
9f30: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
9f40: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
9f50: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
9f60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f70: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
9f80: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
9f90: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
9fa0: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
9fb0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
9fc0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
9fd0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
9fe0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
9ff0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
a000: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
a010: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
a020: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
a030: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
a040: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
a050: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a060: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
a070: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
a080: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
a090: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
a0a0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
a0b0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
a0c0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
a0d0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
a0e0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
a0f0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
a100: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
a110: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
a120: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
a130: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a140: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
a150: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
a160: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a170: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
a180: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
a190: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
a1a0: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
a1b0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
a1c0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
a1d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
a1e0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
a1f0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
a200: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
a210: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a220: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
a230: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
a240: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
a250: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
a260: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
a270: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
a280: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
a290: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
a2a0: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
a2b0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
a2c0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
a2d0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
a2e0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a2f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
a300: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
a310: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
a320: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
a330: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
a340: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a350: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
a360: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
a370: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
a380: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
a390: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a3a0: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
a3b0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
a3c0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
a3d0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
a3e0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
a3f0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
a400: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
a410: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
a420: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
a430: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
a440: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
a450: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
a460: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
a470: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
a480: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
a490: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
a4a0: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
a4b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
a4c0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
a4d0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a4e0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
a4f0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
a500: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
a510: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
a520: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
a530: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
a540: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
a550: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
a560: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
a570: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
a580: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
a590: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
a5a0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
a5b0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
a5c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
a5d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a5e0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
a5f0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
a600: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
a610: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
a620: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
a630: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
a640: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
a650: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
a660: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
a670: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
a680: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
a690: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
a6a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a6b0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
a6c0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
a6d0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
a6e0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
a6f0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
a700: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
a710: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
a720: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
a730: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
a740: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
a750: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a760: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
a770: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
a780: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
a790: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
a7a0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
a7b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a7c0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
a7d0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
a7e0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
a7f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a800: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
a810: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
a820: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
a830: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
a840: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
a850: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
a860: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
a870: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
a880: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
a890: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a8a0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
a8b0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a8c0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a8d0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
a8e0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
a8f0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
a900: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
a910: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
a920: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
a930: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
a940: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a950: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
a960: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
a970: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
a980: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
a990: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
a9a0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
a9b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a9c0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
a9d0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
a9e0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
a9f0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
aa00: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
aa10: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
aa20: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
aa30: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
aa40: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
aa50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
aa60: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
aa70: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
aa80: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
aa90: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
aaa0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
aab0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
aac0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
aad0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
aae0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
aaf0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
ab00: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
ab10: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
ab20: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
ab30: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
ab40: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
ab50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
ab60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
ab70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
ab80: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
ab90: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
aba0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
abb0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
abc0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
abd0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
abe0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
abf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ac00: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
ac10: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
ac20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ac30: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
ac40: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
ac50: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
ac60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
ac70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
ac80: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
ac90: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
aca0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
acb0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
acc0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
acd0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
ace0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
acf0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
ad00: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
ad10: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
ad20: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
ad30: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
ad40: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
ad50: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
ad60: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
ad70: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
ad80: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
ad90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
ada0: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
adb0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
adc0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
add0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
ade0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
adf0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
ae00: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
ae10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
ae20: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
ae30: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
ae40: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
ae50: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ae60: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
ae70: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
ae80: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
ae90: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
aea0: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
aeb0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
aec0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
aed0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
aee0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
aef0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
af00: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
af10: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
af20: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
af30: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
af40: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
af50: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
af60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
af70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
af80: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
af90: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
afa0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
afb0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
afc0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
afd0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
afe0: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
aff0: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
b000: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
b010: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
b020: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
b030: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
b040: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
b050: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
b060: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
b070: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
b080: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
b090: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
b0a0: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
b0b0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
b0c0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
b0d0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
b0e0: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
b0f0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
b100: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
b110: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
b120: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
b130: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
b140: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
b150: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
b160: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
b170: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
b180: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
b190: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
b1a0: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
b1b0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b1c0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
b1d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
b1e0: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
b1f0: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
b200: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
b210: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
b220: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
b230: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
b240: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
b250: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
b260: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
b270: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
b280: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
b290: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
b2a0: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
b2b0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
b2c0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
b2d0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
b2e0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
b2f0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
b300: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
b310: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
b320: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
b330: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
b340: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
b350: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
b360: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
b370: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
b380: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
b390: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
b3a0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
b3b0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
b3c0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
b3d0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
b3e0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
b3f0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
b400: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
b410: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
b420: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
b430: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b440: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
b450: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
b460: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
b470: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b480: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
b490: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
b4a0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
b4b0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
b4c0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
b4d0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
b4e0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
b4f0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
b500: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
b510: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
b520: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
b530: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b540: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
b550: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
b560: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
b570: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
b580: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
b590: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
b5a0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
b5b0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
b5c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
b5d0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
b5e0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
b5f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b600: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
b610: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
b620: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
b630: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b640: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
b650: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b660: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
b670: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b680: 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  () interface sho
b690: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  uld only be used
b6a0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
b6b0: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
b6c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
b6d0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b6e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
b6f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
b700: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
b710: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
b720: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
b730: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
b740: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b750: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
b760: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
b770: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
b780: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
b790: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
b7a0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
b7b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b7c0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
b7d0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
b7e0: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
b7f0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
b800: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
b810: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
b820: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
b830: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
b840: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
b850: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
b860: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
b870: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
b880: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
b890: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
b8a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
b8b0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
b8c0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
b8d0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
b8e0: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
b8f0: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
b900: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
b910: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
b920: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
b930: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
b940: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
b950: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
b960: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
b970: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
b980: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
b990: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
b9a0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
b9b0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b9c0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
b9d0: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
b9e0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
b9f0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
ba00: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
ba10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
ba20: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
ba30: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
ba40: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
ba50: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
ba60: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
ba70: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
ba80: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ba90: 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
baa0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
bab0: 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
bac0: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
bad0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
bae0: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
baf0: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
bb00: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bb10: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
bb20: 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
bb30: 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
bb40: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
bb50: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
bb60: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
bb70: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
bb80: 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
bb90: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
bba0: 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
bbb0: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
bbc0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
bbd0: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
bbe0: 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
bbf0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
bc00: 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
bc10: 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
bc20: 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
bc30: 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
bc40: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
bc50: 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
bc60: 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
bc70: 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
bc80: 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
bc90: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
bca0: 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
bcb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bcc0: 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
bcd0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
bce0: 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
bcf0: 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
bd00: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
bd10: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
bd20: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
bd30: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
bd40: 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
bd50: 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
bd60: 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
bd70: 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
bd80: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
bd90: 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
bda0: 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
bdb0: 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
bdc0: 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78  he xMalloc and x
bdd0: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
bde0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
bdf0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ** malloc() and 
be00: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
be10: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
be20: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
be30: 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65   The xRealloc me
be40: 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c  thod must work l
be50: 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72  ike realloc() fr
be60: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
be70: 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74  C library.** wit
be80: 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20  h the exception 
be90: 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f  that if the seco
bea0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  nd argument to x
beb0: 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c  Realloc is zero,
bec0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73  .** xRealloc mus
bed0: 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69  t be a no-op - i
bee0: 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f  t must not perfo
bef0: 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f  rm any allocatio
bf00: 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  n or.** dealloca
bf10: 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67  tion.  ^SQLite g
bf20: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
bf30: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
bf40: 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
bf50: 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
bf60: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
bf70: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
bf80: 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64  xRoundup..** And
bf90: 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65   so in cases whe
bfa0: 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61  re xRoundup alwa
bfb0: 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ys returns a pos
bfc0: 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a  itive number,.**
bfd0: 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65   xRealloc can pe
bfe0: 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73  rform exactly as
bff0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
c000: 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20  brary realloc() 
c010: 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20  and.** still be 
c020: 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69  in compliance wi
c030: 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63  th this specific
c040: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  ation..**.** xSi
c050: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
c060: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
c070: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
c080: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
c090: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
c0a0: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
c0b0: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
c0c0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
c0d0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
c0e0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
c0f0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
c100: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
c110: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
c120: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
c130: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
c140: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
c150: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
c160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c170: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
c180: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
c190: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
c1a0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
c1b0: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
c1c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
c1d0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
c1e0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
c1f0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
c200: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
c210: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
c220: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
c230: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
c240: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c250: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
c260: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
c270: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
c280: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
c290: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
c2a0: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
c2b0: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
c2c0: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
c2d0: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
c2e0: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
c2f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
c300: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
c310: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
c320: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
c330: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
c340: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
c350: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
c360: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
c370: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
c380: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
c390: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
c3a0: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
c3b0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
c3c0: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
c3d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
c3e0: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
c3f0: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
c400: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
c410: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
c420: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
c430: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
c440: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
c450: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
c460: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
c470: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
c480: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
c490: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
c4a0: 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
c4b0: 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
c4c0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
c4d0: 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
c4e0: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
c4f0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
c500: 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
c510: 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
c520: 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
c530: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
c540: 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
c550: 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
c560: 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
c570: 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
c580: 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
c590: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
c5a0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
c5b0: 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
c5c0: 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
c5d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c5e0: 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
c5f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
c600: 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
c610: 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
c620: 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
c630: 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
c640: 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
c650: 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
c660: 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
c670: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
c680: 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
c690: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
c6a0: 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
c6b0: 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
c6c0: 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
c6d0: 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
c6e0: 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
c6f0: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
c700: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
c710: 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
c720: 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
c730: 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
c740: 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
c750: 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
c760: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c770: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
c780: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c790: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
c7a0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
c7b0: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
c7c0: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
c7d0: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
c7e0: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
c7f0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
c800: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c810: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
c820: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
c830: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
c840: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
c850: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
c860: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c870: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
c880: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c890: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
c8a0: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
c8b0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
c8c0: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
c8d0: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
c8e0: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
c8f0: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
c900: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
c910: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
c920: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
c930: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
c940: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
c950: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
c960: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
c970: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
c980: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c990: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
c9a0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
c9b0: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
c9c0: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
c9d0: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
c9e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
c9f0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
ca00: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
ca10: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
ca20: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
ca30: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
ca40: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
ca50: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
ca60: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
ca70: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
ca80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
ca90: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
caa0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
cab0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
cac0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
cad0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
cae0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
caf0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
cb00: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
cb10: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
cb20: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
cb30: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
cb40: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
cb50: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
cb60: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
cb70: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
cb80: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
cb90: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
cba0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
cbb0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
cbc0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
cbd0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
cbe0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
cbf0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
cc00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
cc10: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
cc20: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
cc30: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
cc40: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
cc50: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
cc60: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
cc70: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
cc80: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
cc90: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
cca0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
ccb0: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
ccc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
ccd0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
cce0: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
ccf0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
cd00: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
cd10: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
cd20: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
cd30: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
cd40: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
cd50: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
cd60: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
cd70: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
cd80: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
cd90: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
cda0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
cdb0: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
cdc0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
cdd0: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
cde0: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
cdf0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
ce00: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
ce10: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
ce20: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
ce30: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
ce40: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
ce50: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ce60: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
ce70: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
ce80: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ce90: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
cea0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
ceb0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
cec0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
ced0: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
cee0: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
cef0: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
cf00: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
cf10: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
cf20: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
cf30: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
cf40: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
cf50: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
cf60: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
cf70: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
cf80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
cf90: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
cfa0: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
cfb0: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
cfc0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
cfd0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
cfe0: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
cff0: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
d000: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
d010: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
d020: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
d030: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
d040: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
d050: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
d060: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
d070: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
d080: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
d090: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
d0a0: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
d0b0: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d0c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d0d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d0e0: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d0f0: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d100: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d110: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d120: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d130: 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
d140: 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
d150: 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
d160: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d170: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
d180: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
d190: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
d1a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d1b0: 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
d1c0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
d1d0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d1e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d1f0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
d200: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d210: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d220: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d230: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d240: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d250: 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
d260: 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
d270: 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
d280: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
d290: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
d2a0: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
d2b0: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
d2c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d2d0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
d2e0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
d2f0: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
d300: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
d310: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
d320: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
d330: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
d340: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
d350: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
d360: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
d370: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
d380: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
d390: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
d3a0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
d3b0: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
d3c0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
d3d0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
d3e0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
d3f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d400: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
d410: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
d420: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
d430: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
d440: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
d450: 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
d460: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
d470: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
d480: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
d490: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
d4a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d4b0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
d4c0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
d4d0: 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
d4e0: 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
d4f0: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
d500: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
d510: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
d520: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
d530: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
d540: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d550: 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
d560: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
d570: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d580: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d590: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
d5a0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
d5b0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d5c0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d5d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d5e0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d5f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
d600: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d610: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d620: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d630: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d640: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
d650: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
d660: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
d670: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
d680: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
d690: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
d6a0: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
d6b0: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
d6c0: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
d6d0: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
d6e0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
d6f0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
d700: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
d710: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
d720: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
d730: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
d740: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d750: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
d760: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
d770: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d780: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
d790: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
d7a0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
d7b0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
d7c0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d7d0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
d7e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
d7f0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
d800: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
d810: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
d820: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
d830: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d840: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
d850: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
d860: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
d870: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
d880: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
d890: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
d8a0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
d8b0: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
d8c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
d8d0: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
d8e0: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
d8f0: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
d900: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d910: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d920: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
d930: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
d940: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
d950: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
d960: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
d970: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
d980: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
d990: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
d9a0: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
d9b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
d9c0: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
d9d0: 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
d9e0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
d9f0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
da00: 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
da10: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
da20: 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
da30: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
da40: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
da50: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
da60: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
da70: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
da80: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
da90: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
daa0: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
dab0: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
dac0: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
dad0: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
dae0: 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
daf0: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
db00: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
db10: 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
db20: 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
db30: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
db40: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
db50: 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
db60: 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
db70: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
db80: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
db90: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
dba0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dbb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
dbc0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
dbd0: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
dbe0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
dbf0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
dc00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
dc10: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
dc20: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
dc30: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
dc40: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
dc50: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
dc60: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
dc70: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
dc80: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
dc90: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
dca0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
dcb0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
dcc0: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
dcd0: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
dce0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
dcf0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
dd00: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
dd10: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
dd20: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
dd30: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
dd40: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
dd50: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
dd60: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
dd70: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
dd80: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
dd90: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
dda0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
ddb0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ddc0: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
ddd0: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
dde0: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
ddf0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
de00: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
de10: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
de20: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
de30: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
de40: 62 75 66 66 65 72 20 70 65 72 20 74 68 72 65 61  buffer per threa
de50: 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
de60: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
de70: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
de80: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
de90: 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ads.  ^SQLite wi
dea0: 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75  ll.** never requ
deb0: 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
dec0: 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
ded0: 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74  e than 6 times t
dee0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
def0: 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
df00: 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
df10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61   additional scra
df20: 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
df30: 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72  d .** what is pr
df40: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
df50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
df60: 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
df70: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
df80: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
df90: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
dfa0: 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
dfb0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
dfc0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
dfd0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
dfe0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
dff0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
e000: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
e010: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
e020: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
e030: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
e040: 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
e050: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
e060: 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  emenation.  .** 
e070: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
e080: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
e090: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
e0a0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
e0b0: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
e0c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
e0d0: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
e0e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
e0f0: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
e100: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e110: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e120: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
e130: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
e140: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
e150: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
e160: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
e170: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
e180: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
e190: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
e1a0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
e1b0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
e1c0: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
e1d0: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
e1e0: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
e1f0: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
e200: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
e210: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
e220: 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
e230: 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
e240: 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
e250: 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
e260: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
e270: 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
e280: 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
e290: 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
e2a0: 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
e2b0: 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
e2c0: 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
e2d0: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
e2e0: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
e2f0: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
e300: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
e310: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
e320: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
e330: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
e340: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
e350: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e360: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
e370: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
e380: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
e390: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
e3a0: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
e3b0: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
e3c0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
e3d0: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
e3e0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e3f0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
e400: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
e410: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
e420: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
e430: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
e440: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
e450: 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  .** ^The impleme
e460: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73  ntation might us
e470: 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  e one or more of
e480: 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74   the N buffers t
e490: 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72  o hold .** memor
e4a0: 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66  y accounting inf
e4b0: 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f  ormation. The po
e4c0: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
e4d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
e4e0: 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
e4f0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
e500: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
e510: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
e520: 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
e530: 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
e540: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e550: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
e560: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e570: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
e580: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
e590: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
e5a0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
e5b0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
e5c0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
e5d0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
e5e0: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
e5f0: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
e600: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
e610: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
e620: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
e630: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
e640: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
e650: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
e660: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
e670: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
e680: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
e690: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
e6a0: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
e6b0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
e6c0: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
e6d0: 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
e6e0: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
e6f0: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
e700: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
e710: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
e720: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
e730: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e740: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
e750: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
e760: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
e770: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
e780: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
e790: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
e7a0: 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
e7b0: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
e7c0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
e7d0: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
e7e0: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
e7f0: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
e800: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
e810: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
e820: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
e830: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
e840: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
e850: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
e860: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
e870: 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
e880: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
e890: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
e8a0: 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
e8b0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
e8c0: 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
e8d0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
e8e0: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
e8f0: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
e900: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
e910: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e920: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
e930: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
e940: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
e950: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
e960: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
e970: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
e980: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
e990: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
e9a0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
e9b0: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
e9c0: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
e9d0: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
e9e0: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e9f0: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
ea00: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
ea10: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
ea20: 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
ea30: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
ea40: 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
ea50: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
ea60: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
ea70: 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
ea80: 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
ea90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eaa0: 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
eab0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
eac0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ead0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
eae0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
eaf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
eb00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
eb10: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
eb20: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
eb30: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
eb40: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
eb50: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
eb60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
eb70: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
eb80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
eb90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
eba0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
ebb0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
ebc0: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
ebd0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ebe0: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
ebf0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
ec00: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
ec10: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
ec20: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
ec30: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
ec40: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
ec50: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ec60: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ec70: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
ec80: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
ec90: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
eca0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
ecb0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
ecc0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
ecd0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
ece0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
ecf0: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
ed00: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
ed10: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
ed20: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
ed30: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
ed40: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
ed50: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
ed60: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
ed70: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
ed80: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
ed90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
eda0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
edb0: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
edc0: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
edd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ede0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
edf0: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
ee00: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
ee10: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
ee20: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
ee30: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
ee40: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
ee50: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
ee60: 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
ee70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ee80: 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
ee90: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
eea0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
eeb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
eec0: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
eed0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
eee0: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
eef0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
ef00: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
ef10: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ef20: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
ef30: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
ef40: 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
ef50: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
ef60: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
ef70: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
ef80: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
ef90: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
efa0: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
efb0: 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
efc0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
efd0: 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
efe0: 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
eff0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
f000: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
f010: 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
f020: 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
f030: 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
f040: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f050: 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
f060: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
f070: 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
f080: 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
f090: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
f0a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
f0b0: 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
f0c0: 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
f0d0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f0e0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
f0f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f100: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f110: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f120: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f130: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
f140: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f150: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
f160: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
f170: 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
f180: 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
f190: 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
f1a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
f1b0: 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
f1c0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
f1d0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
f1e0: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f1f0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f200: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f210: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f220: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f230: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f240: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f250: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f260: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f270: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
f280: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f290: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53  hods] object.  S
f2a0: 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
f2b0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
f2c0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
f2d0: 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
f2e0: 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
f2f0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f300: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
f310: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
f320: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f330: 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
f340: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
f350: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
f360: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
f370: 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
f380: 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
f390: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
f3a0: 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
f3b0: 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
f3c0: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
f3d0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
f3e0: 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
f3f0: 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
f400: 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
f410: 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
f420: 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
f430: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
f440: 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
f450: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
f460: 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
f470: 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
f480: 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
f490: 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
f4a0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
f4b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f4c0: 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
f4d0: 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
f4e0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
f4f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f500: 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
f510: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
f520: 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
f530: 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
f540: 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
f550: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f560: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
f570: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
f580: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f590: 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
f5a0: 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
f5b0: 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
f5c0: 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
f5d0: 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
f5e0: 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
f5f0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
f600: 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
f610: 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
f620: 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
f630: 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
f640: 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
f650: 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
f660: 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
f670: 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
f680: 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
f690: 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
f6a0: 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
f6b0: 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
f6c0: 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
f6d0: 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
f6e0: 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
f6f0: 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
f700: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
f710: 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
f720: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
f730: 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
f740: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
f750: 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
f760: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
f770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f780: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
f790: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
f7a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f7b0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
f7c0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
f7d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f7e0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
f7f0: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
f800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f810: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
f820: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
f830: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f840: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f850: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f860: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
f870: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f880: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f890: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
f8a0: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
f8b0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
f8c0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
f8d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f8e0: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
f8f0: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
f900: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
f910: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f920: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
f930: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
f940: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
f950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f960: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
f970: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
f980: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
f990: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
f9a0: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
f9b0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f9c0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f9d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f9e0: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
f9f0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
fa00: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
fa10: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
fa20: 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
fa30: 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
fa40: 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
fa50: 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
fa60: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
fa70: 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
fa80: 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
fa90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
faa0: 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
fab0: 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
fac0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
fad0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
fae0: 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
faf0: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  5  /* sqlite3_pc
fb00: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
fb10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fb20: 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
fb30: 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
fb40: 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  , void* */../*.*
fb50: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
fb60: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
fb70: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
fb80: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
fb90: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
fba0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
fbb0: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
fbc0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
fbd0: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
fbe0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
fbf0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
fc00: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
fc10: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
fc20: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
fc30: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
fc40: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
fc50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
fc60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
fc70: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
fc80: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
fc90: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
fca0: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
fcb0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
fcc0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
fcd0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
fce0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
fcf0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
fd00: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
fd10: 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
fd20: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
fd30: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
fd40: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
fd50: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
fd60: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
fd70: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
fd80: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
fd90: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
fda0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
fdb0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
fdc0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
fdd0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
fde0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
fdf0: 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
fe00: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
fe10: 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
fe20: 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
fe30: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
fe40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
fe50: 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
fe60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
fe70: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
fe80: 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
fe90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
fea0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
feb0: 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
fec0: 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20  er to an memory 
fed0: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
fee0: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
fef0: 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
ff00: 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
ff10: 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
ff20: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
ff30: 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
ff40: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
ff50: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
ff60: 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
ff70: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
ff80: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
ff90: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
ffa0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
ffb0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
ffc0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
ffd0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
ffe0: 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
fff0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
10000 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
10010 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
10020 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
10030 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10040 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
10050 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
10060 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
10070 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
10080 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
10090 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
100a0 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
100b0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
100c0 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
100d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
100e0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
100f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10100 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
10110 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
10120 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
10130 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
10140 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
10150 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
10160 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
10170 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
10180 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
10190 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
101a0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
101b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
101c0 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
101d0 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
101e0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
101f0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
10200 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
10210 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
10220 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
10230 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
10240 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
10250 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
10260 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10270 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
10280 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
10290 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
102a0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
102b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
102c0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
102d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
102e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
102f0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
10300 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
10310 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
10320 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
10330 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
10340 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
10350 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
10360 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
10370 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
10380 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
10390 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
103a0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
103b0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
103c0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
103d0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
103e0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
103f0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
10400 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
10410 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
10420 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
10430 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
10440 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
10450 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
10460 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
10470 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
10480 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
10490 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
104a0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
104b0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
104c0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
104d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
104e0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
104f0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
10500 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
10510 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
10520 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
10530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10540 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10550 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
10560 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
10570 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
10580 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
10590 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
105a0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
105b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
105c0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
105d0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
105e0 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
105f0 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
10600 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
10610 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
10620 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
10630 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
10640 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
10650 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
10660 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
10670 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
10680 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
10690 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
106a0 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
106b0 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
106c0 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
106d0 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  ger fired.)^.**.
106e0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
106f0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
10700 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
10710 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
10720 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
10730 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
10740 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
10750 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10760 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
10770 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
10780 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
10790 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
107a0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
107b0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
107c0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
107d0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
107e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
107f0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
10800 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
10810 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
10820 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
10830 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
10840 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
10850 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
10860 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
10870 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
10880 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
10890 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
108a0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
108b0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
108c0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
108d0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
108e0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
108f0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
10900 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10910 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
10920 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
10930 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
10940 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
10950 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
10960 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
10970 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
10980 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
10990 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
109a0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
109b0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
109c0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
109d0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
109e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
109f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
10a00 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
10a10 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
10a20 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
10a30 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
10a40 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
10a50 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
10a60 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10a70 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
10a80 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
10a90 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
10aa0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
10ab0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
10ac0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
10ad0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
10ae0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10af0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
10b00 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
10b10 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10b20 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10b30 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10b40 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
10b50 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
10b60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
10b70 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10b80 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
10b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
10ba0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
10bb0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
10bc0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
10bd0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
10be0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
10bf0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
10c00 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
10c10 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
10c20 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
10c30 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
10c40 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
10c50 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
10c60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10c70 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
10c80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10c90 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
10ca0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
10cb0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
10cc0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
10cd0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
10ce0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
10cf0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
10d00 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
10d10 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
10d20 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
10d30 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
10d40 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
10d50 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
10d60 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
10d70 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
10d80 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
10d90 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
10da0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
10db0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
10dc0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
10dd0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
10de0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
10df0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
10e00 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
10e10 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
10e20 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
10e30 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
10e40 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
10e50 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
10e60 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
10e70 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
10e80 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
10e90 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
10ea0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
10eb0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
10ec0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
10ed0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
10ee0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
10ef0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
10f00 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
10f10 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
10f20 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
10f30 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
10f40 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
10f50 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
10f60 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
10f70 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
10f80 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
10f90 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
10fa0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
10fb0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
10fc0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
10fd0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
10fe0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
10ff0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
11000 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
11010 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
11020 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
11030 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
11040 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
11050 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
11060 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
11070 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
11080 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
11090 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
110a0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
110b0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
110c0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
110d0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
110e0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
110f0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
11100 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
11110 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
11120 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
11130 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
11140 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
11150 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
11160 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
11170 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
11180 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
11190 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
111a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
111b0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
111c0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
111d0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
111e0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
111f0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
11200 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
11210 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
11220 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
11230 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
11240 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
11250 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
11260 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
11270 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
11280 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
11290 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
112a0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
112b0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
112c0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
112d0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
112e0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
112f0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
11300 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
11310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
11320 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
11330 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
11340 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
11350 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
11360 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
11370 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
11380 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
11390 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
113a0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
113b0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
113c0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
113d0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
113e0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
113f0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
11400 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
11410 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
11420 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
11430 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
11440 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
11450 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
11460 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11470 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
11480 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
11490 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
114a0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
114b0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
114c0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
114d0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
114e0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
114f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11500 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
11510 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11520 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
11530 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
11540 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
11550 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
11560 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
11570 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
11580 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
115a0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
115b0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
115c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
115d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
115e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
115f0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
11600 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
11610 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
11620 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
11630 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
11640 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
11650 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
11660 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
11670 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
11680 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
11690 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
116a0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
116b0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
116c0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
116d0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
116e0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
116f0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
11700 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
11710 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
11720 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
11730 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
11740 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
11750 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
11760 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
11770 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
11780 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
11790 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
117a0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
117b0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
117c0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
117d0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
117e0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
117f0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
11800 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
11810 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
11820 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
11830 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
11840 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
11850 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11860 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
11870 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
11880 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
11890 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
118a0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
118b0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
118c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
118d0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
118e0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
118f0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
11900 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
11910 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
11920 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
11930 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
11940 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
11950 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
11960 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
11970 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
11980 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
11990 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
119a0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
119b0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
119c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
119d0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
119e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
119f0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11a00 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11a10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
11a20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
11a30 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
11a40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11a50 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
11a60 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11a70 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
11a80 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
11a90 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
11aa0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
11ab0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
11ac0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
11ad0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
11ae0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
11af0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
11b00 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
11b10 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
11b20 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
11b30 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
11b40 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
11b50 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
11b60 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
11b70 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
11b80 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
11b90 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
11ba0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
11bb0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
11bc0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
11bd0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
11be0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
11bf0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
11c00 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
11c10 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
11c20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
11c30 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
11c40 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
11c50 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
11c60 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
11c70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11c80 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
11c90 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
11ca0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
11cb0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
11cc0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
11cd0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
11ce0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
11cf0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
11d00 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
11d10 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11d20 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
11d30 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
11d40 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
11d50 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
11d60 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
11d70 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
11d80 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
11d90 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
11da0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
11db0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
11dc0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
11dd0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
11de0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
11df0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
11e00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11e10 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
11e20 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
11e30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
11e40 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
11e50 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
11e60 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
11e70 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
11e80 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
11e90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
11ea0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
11eb0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
11ec0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
11ed0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
11ee0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
11ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11f00 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
11f10 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
11f20 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
11f30 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
11f40 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11f50 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
11f60 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
11f70 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
11f80 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
11f90 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
11fa0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
11fb0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
11fc0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
11fd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11fe0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
11ff0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
12000 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
12010 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
12020 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
12030 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
12040 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
12050 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
12060 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
12070 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
12080 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
12090 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
120a0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
120b0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
120c0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
120d0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
120e0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
120f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
12100 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12110 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12120 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
12130 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
12140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
12150 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
12160 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
12170 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
12180 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
12190 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
121a0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
121b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
121c0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
121d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
121e0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
121f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
12200 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
12210 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12220 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
12230 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
12240 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
12250 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
12260 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
12270 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
12280 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
12290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
122a0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
122b0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
122c0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
122d0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
122e0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
122f0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
12300 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
12310 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
12320 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
12330 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
12340 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
12350 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
12360 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
12370 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
12380 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
12390 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
123a0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
123b0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
123c0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
123d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
123e0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
123f0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
12400 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
12410 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
12420 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
12430 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
12440 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
12450 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
12460 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
12470 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
12480 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
12490 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
124a0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
124b0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
124c0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
124d0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
124e0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
124f0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
12500 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
12510 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
12520 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
12530 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
12540 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
12550 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
12560 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
12570 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
12580 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
12590 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
125a0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
125b0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
125c0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
125d0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
125e0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
125f0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
12600 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
12610 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
12620 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
12630 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12640 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
12650 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
12660 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
12670 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
12680 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
12690 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
126a0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
126b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
126c0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
126d0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
126e0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
126f0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
12700 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
12710 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
12720 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
12730 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
12740 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
12750 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
12760 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
12770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12780 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
12790 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
127a0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
127b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
127c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
127d0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
127e0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
127f0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
12800 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
12810 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
12820 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
12830 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
12840 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
12850 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
12860 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
12870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12880 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
12890 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
128a0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
128b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
128c0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
128d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
128e0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
128f0 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
12900 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
12910 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
12920 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
12930 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
12940 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
12950 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
12960 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
12970 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
12980 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
12990 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
129a0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
129b0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
129c0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
129d0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
129e0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
129f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
12a00 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
12a10 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
12a20 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
12a30 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
12a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
12a50 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
12a60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
12a70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
12a80 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
12a90 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
12aa0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
12ab0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
12ac0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
12ad0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12ae0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
12af0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
12b00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
12b10 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
12b20 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
12b30 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
12b40 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
12b50 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
12b60 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
12b70 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
12b80 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
12b90 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
12ba0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
12bb0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
12bc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
12bd0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12be0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
12bf0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
12c00 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
12c10 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
12c20 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
12c30 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
12c40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
12c50 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
12c60 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
12c70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
12c80 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
12c90 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
12ca0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
12cb0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
12cc0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
12cd0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
12ce0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
12cf0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
12d00 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
12d10 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
12d20 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
12d30 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
12d40 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
12d50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
12d60 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
12d70 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12d80 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
12d90 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
12da0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
12db0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
12dc0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
12dd0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
12de0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
12df0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
12e00 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
12e10 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
12e20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
12e30 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
12e40 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
12e50 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
12e60 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
12e70 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
12e80 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
12e90 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
12ea0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
12eb0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
12ec0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
12ed0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
12ee0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
12ef0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
12f00 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
12f10 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
12f20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
12f30 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
12f40 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
12f50 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
12f60 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
12f70 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
12f80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
12f90 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
12fa0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
12fb0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
12fc0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
12fd0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
12fe0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
12ff0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
13000 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
13010 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
13020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
13030 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
13040 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
13050 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
13060 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
13070 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
13080 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13090 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
130a0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
130b0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
130c0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
130d0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
130e0 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
130f0 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
13100 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
13110 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
13120 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
13130 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
13140 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
13150 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
13160 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
13170 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
13180 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
13190 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
131a0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
131b0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
131c0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
131d0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
131e0 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
131f0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
13200 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
13210 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
13220 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
13230 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
13240 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
13250 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
13260 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
13270 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
13280 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
13290 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
132a0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
132b0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
132c0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
132d0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
132e0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
132f0 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
13300 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
13310 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
13320 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
13330 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
13340 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13350 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
13360 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13370 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
13380 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
13390 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
133a0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
133b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
133c0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
133d0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
133e0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
133f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13400 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
13410 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
13420 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
13430 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
13440 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
13450 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
13460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
13470 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
13480 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
13490 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
134a0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
134b0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
134c0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
134d0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
134e0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
134f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13500 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
13510 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13520 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
13530 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
13540 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
13550 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
13560 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
13570 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
13580 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13590 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
135a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
135b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
135c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
135d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
135e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
135f0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
13600 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
13610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
13620 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
13630 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
13640 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
13650 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
13660 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
13670 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
13680 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
13690 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
136a0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
136b0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
136c0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
136d0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
136e0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
136f0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
13700 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13710 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
13720 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
13730 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
13740 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
13750 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
13760 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
13770 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
13780 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
13790 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
137a0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
137b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
137c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
137d0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
137e0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
137f0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
13800 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
13810 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
13820 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
13830 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
13840 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
13850 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
13860 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
13870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13880 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
13890 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
138a0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
138b0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
138c0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
138d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
138e0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
138f0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
13900 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
13910 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
13920 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
13930 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
13940 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
13950 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
13960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
13970 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
13980 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
13990 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69  eries.**.** Defi
139a0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
139b0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
139c0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
139d0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
139e0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
139f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
13a00 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
13a10 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
13a20 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
13a30 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
13a40 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
13a50 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
13a60 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
13a70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
13a80 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
13a90 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
13aa0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
13ab0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
13ac0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
13ad0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
13ae0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
13af0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
13b00 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
13b10 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
13b20 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
13b30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
13b40 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
13b50 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
13b60 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
13b70 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
13b80 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
13b90 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
13ba0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
13bb0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
13bc0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
13bd0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
13be0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
13bf0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
13c00 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
13c10 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
13c20 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
13c30 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
13c40 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
13c50 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
13c60 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
13c70 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
13c80 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
13c90 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
13ca0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
13cb0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
13cc0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
13cd0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
13ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
13cf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
13d00 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
13d10 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
13d20 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
13d30 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
13d40 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
13d50 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
13d60 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
13d70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
13d80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
13d90 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
13da0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
13db0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
13dc0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
13dd0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
13de0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
13df0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
13e00 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
13e10 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
13e20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
13e30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
13e40 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
13e50 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
13e60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13e70 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
13e80 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
13e90 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
13ea0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
13eb0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
13ec0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
13ed0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
13ee0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
13ef0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
13f00 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
13f10 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
13f20 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
13f30 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
13f40 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
13f50 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
13f60 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
13f70 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
13f80 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
13f90 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
13fa0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
13fb0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13fc0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13fd0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
13fe0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13ff0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
14000 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
14010 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
14020 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
14030 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14040 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
14050 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14060 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
14070 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14080 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
14090 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
140a0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
140b0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
140c0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
140d0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
140e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
140f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
14100 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14110 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14120 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14130 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14140 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14150 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14160 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14170 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14180 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
14190 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
141a0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
141b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
141c0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
141d0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
141e0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
141f0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
14200 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
14210 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
14220 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
14230 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65   should pass the
14240 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
14250 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
14260 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
14270 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
14280 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14290 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
142a0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
142b0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
142c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
142d0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
142e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
142f0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
14300 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14310 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
14320 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
14330 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
14340 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
14350 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
14360 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
14370 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
14380 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
14390 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
143a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
143b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
143c0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
143d0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
143e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
143f0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
14400 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
14410 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
14420 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
14430 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
14440 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
14450 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
14460 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
14470 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
14480 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
14490 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
144a0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
144b0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
144c0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
144d0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
144e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
144f0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
14500 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
14510 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
14520 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
14530 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
14540 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e  te3_errmsg()].)^
14550 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14560 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
14570 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
14580 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
14590 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
145a0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
145b0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
145c0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
145d0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
145e0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
145f0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
14600 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
14610 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
14620 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
14630 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
14640 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
14650 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
14660 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
14670 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
14680 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
14690 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
146a0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
146b0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
146c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
146d0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
146e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
146f0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
14700 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
14710 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
14720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
14730 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
14740 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
14750 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
14760 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
14770 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
14780 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
14790 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
147a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
147b0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
147c0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
147d0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
147e0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
147f0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14800 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
14810 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
14820 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
14830 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
14840 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
14850 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
14860 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
14870 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
14880 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
14890 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
148a0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
148b0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
148c0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
148d0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
148e0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71  g..**.** ^(In sq
148f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14900 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
14910 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
14920 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
14930 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
14940 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
14950 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
14960 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
14970 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
14980 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
14990 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
149a0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
149b0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
149c0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
149d0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
149e0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
149f0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
14a00 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
14a10 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
14a20 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
14a30 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
14a40 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
14a50 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
14a60 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14a70 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
14a80 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
14a90 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
14aa0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14ab0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
14ac0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
14ad0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
14ae0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
14af0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
14b00 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
14b10 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
14b20 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
14b30 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
14b40 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
14b50 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
14b60 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
14b70 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
14b80 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
14b90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14ba0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
14bb0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
14bc0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
14bd0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
14be0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
14bf0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
14c00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14c10 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
14c20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
14c30 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
14c40 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
14c50 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
14c60 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
14c70 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
14c80 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
14c90 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
14ca0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
14cb0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
14cc0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
14cd0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
14ce0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
14cf0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
14d00 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
14d10 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
14d20 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
14d30 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
14d40 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
14d50 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
14d60 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
14d70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
14d80 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
14d90 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
14da0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
14db0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
14dc0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
14dd0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
14de0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
14df0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
14e00 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
14e10 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
14e20 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
14e30 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
14e40 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
14e50 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
14e60 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
14e70 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
14e80 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
14e90 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
14ea0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
14eb0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
14ec0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
14ed0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
14ee0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
14ef0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
14f00 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
14f10 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
14f20 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
14f30 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
14f40 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
14f50 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
14f60 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
14f70 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
14f80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14f90 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14fa0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
14fb0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
14fc0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14fd0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
14fe0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
14ff0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
15000 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
15010 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15020 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
15030 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
15040 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
15050 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
15060 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
15070 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
15080 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
15090 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
150a0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
150b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
150c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
150d0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
150e0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
150f0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
15100 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
15110 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
15120 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
15130 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
15140 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15150 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
15160 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15170 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
15180 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
15190 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
151a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
151b0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
151c0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
151d0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
151e0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
151f0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
15200 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
15210 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15220 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
15230 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
15240 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
15250 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
15260 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
15270 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
15280 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
15290 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
152a0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
152b0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
152c0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
152d0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
152e0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
152f0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
15300 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
15310 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
15320 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
15330 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
15340 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
15350 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
15360 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
15370 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
15380 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
15390 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
153a0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
153b0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
153c0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
153d0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
153e0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
153f0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
15400 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
15410 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
15420 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
15430 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15440 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
15450 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
15460 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15470 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
15480 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
15490 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
154a0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
154b0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
154c0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
154d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
154e0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
154f0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
15500 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
15510 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
15520 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
15530 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
15540 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
15550 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
15560 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
15570 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
15580 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
15590 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
155a0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
155b0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
155c0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
155d0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
155e0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
155f0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
15600 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
15610 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
15620 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
15630 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
15640 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
15650 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
15660 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
15670 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
15680 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
15690 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
156a0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
156b0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
156c0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
156d0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
156e0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
156f0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
15700 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
15710 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
15720 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
15730 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
15740 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
15750 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
15760 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
15770 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
15780 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
15790 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
157a0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
157b0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
157c0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
157d0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
157e0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
157f0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
15800 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
15810 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15820 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
15830 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
15840 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
15850 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
15860 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
15870 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
15880 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
15890 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
158a0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
158b0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
158c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
158d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
158e0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
158f0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
15900 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
15910 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
15920 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
15930 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
15940 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
15950 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
15960 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
15970 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
15980 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
15990 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
159a0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
159b0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
159c0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
159d0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
159e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
159f0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
15a00 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
15a10 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
15a20 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
15a30 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
15a40 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
15a50 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
15a60 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
15a70 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
15a80 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
15a90 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
15aa0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
15ab0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
15ac0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
15ad0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
15ae0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
15af0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
15b00 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
15b10 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
15b20 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
15b30 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
15b40 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
15b50 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
15b60 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
15b70 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
15b80 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
15b90 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
15ba0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
15bb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15bc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
15bd0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
15be0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
15bf0 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
15c00 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
15c10 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
15c20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15c30 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
15c40 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
15c50 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
15c60 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
15c70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15c80 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
15c90 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
15ca0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
15cb0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
15cc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15cd0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
15ce0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15cf0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
15d00 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
15d10 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
15d20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
15d30 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
15d40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15d50 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15d60 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
15d70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15d80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
15d90 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
15da0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
15db0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
15dc0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
15dd0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
15de0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
15df0 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
15e00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15e10 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15e20 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
15e30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
15e40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15e50 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
15e60 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
15e70 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
15e80 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
15e90 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
15ea0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
15eb0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
15ec0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
15ed0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
15ee0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
15ef0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
15f00 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
15f10 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
15f20 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
15f30 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
15f40 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
15f50 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
15f60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15f70 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
15f80 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
15f90 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
15fa0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
15fb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
15fc0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
15fd0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
15fe0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
15ff0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
16000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16010 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
16020 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
16030 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
16040 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  ndary..**.** In 
16050 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
16060 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
16070 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
16080 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
16090 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
160a0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
160b0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
160c0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
160d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
160e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
160f0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
16100 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
16110 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
16120 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
16130 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
16140 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
16150 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
16160 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
16170 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
16180 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
16190 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
161a0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
161b0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
161c0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
161d0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
161e0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
161f0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
16200 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
16210 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
16220 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
16230 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
16240 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
16250 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
16260 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
16270 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
16280 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
16290 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
162a0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
162b0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
162c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
162d0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
162e0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
162f0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
16300 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
16310 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
16320 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
16330 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
16340 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
16350 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
16360 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
16370 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16380 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
16390 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
163a0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
163b0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
163c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
163d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
163e0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
163f0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
16400 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
16410 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
16420 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
16430 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
16440 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
16450 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
16460 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
16470 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
16480 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
16490 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
164a0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
164b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
164c0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
164d0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
164e0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
164f0 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
16500 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
16510 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
16520 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
16530 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16540 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
16550 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
16560 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
16570 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
16580 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
16590 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
165a0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
165b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
165c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
165d0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
165e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
165f0 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
16600 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
16610 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
16620 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
16630 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
16640 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16650 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
16660 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
16670 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
16680 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
16690 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
166a0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
166b0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
166c0 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
166d0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
166e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
166f0 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
16700 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16710 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
16720 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
16730 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
16740 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
16750 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
16760 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
16770 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
16780 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
16790 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
167a0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
167b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
167c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
167d0 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
167e0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
167f0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
16800 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
16810 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
16820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
16830 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
16840 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
16850 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
16860 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16870 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
16880 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
16890 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
168a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
168b0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
168c0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
168d0 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
168e0 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
168f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
16900 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
16910 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
16920 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
16930 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
16940 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
16950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16960 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
16970 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
16980 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
16990 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
169a0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
169b0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
169c0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
169d0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
169e0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
169f0 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
16a00 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
16a10 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
16a20 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
16a30 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
16a40 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
16a50 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
16a60 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
16a70 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
16a80 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
16a90 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
16aa0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
16ab0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
16ac0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
16ad0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
16ae0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
16af0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
16b00 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
16b10 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
16b20 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
16b30 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
16b40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16b50 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
16b60 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
16b70 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
16b80 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
16b90 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
16ba0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
16bb0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
16bc0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
16bd0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
16be0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
16bf0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
16c00 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
16c10 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
16c20 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
16c30 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
16c40 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
16c50 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
16c60 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
16c70 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
16c80 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
16c90 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
16ca0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
16cb0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
16cc0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
16cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
16ce0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
16cf0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
16d00 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
16d10 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
16d20 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
16d30 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
16d40 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
16d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16d60 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
16d70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16d80 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
16d90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16da0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
16db0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
16dc0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
16dd0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
16de0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
16df0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
16e00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
16e10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16e20 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
16e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
16e40 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
16e50 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
16e60 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
16e70 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
16e80 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
16e90 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
16ea0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
16eb0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
16ec0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16ed0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
16ee0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
16ef0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
16f00 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
16f10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
16f20 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
16f30 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
16f40 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
16f50 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
16f60 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
16f70 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
16f80 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
16f90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
16fa0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
16fb0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
16fc0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
16fd0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
16fe0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
16ff0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
17000 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
17010 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
17020 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
17030 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
17040 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
17050 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
17060 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
17070 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
17080 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
17090 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
170a0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
170b0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
170c0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
170d0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
170e0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
170f0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
17100 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
17110 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
17120 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
17130 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
17140 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
17150 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
17160 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
17170 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
17180 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17190 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
171a0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
171b0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
171c0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
171d0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
171e0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
171f0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
17200 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
17210 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
17220 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17230 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17240 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
17250 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
17260 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
17270 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
17280 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
17290 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
172a0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
172b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
172c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
172d0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
172e0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
172f0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
17300 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
17310 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
17320 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
17330 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
17340 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
17350 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
17360 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
17370 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
17380 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
17390 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
173a0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
173b0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
173c0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
173d0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
173e0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
173f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17400 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
17410 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
17420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
17430 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
17440 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
17450 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
17460 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
17470 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
17480 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
17490 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
174a0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
174b0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
174c0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
174d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
174e0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
174f0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
17500 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
17510 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
17520 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
17530 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
17540 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
17550 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
17560 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
17570 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
17580 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
17590 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
175a0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
175b0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
175c0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
175d0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
175e0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
175f0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
17600 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
17610 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
17620 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
17630 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
17640 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
17650 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
17660 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
17670 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
17680 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
17690 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
176a0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
176b0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
176c0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
176d0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
176e0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
176f0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
17700 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
17710 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
17720 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
17730 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
17740 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
17750 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
17760 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
17770 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
17780 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
17790 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
177a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
177b0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
177c0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
177d0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
177e0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
177f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
17800 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
17810 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
17820 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
17830 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
17840 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
17850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17860 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
17870 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
17880 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
17890 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
178a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
178b0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
178c0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
178d0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
178e0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
178f0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
17900 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
17910 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
17920 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
17930 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
17940 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
17950 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
17960 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
17970 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
17980 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
17990 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
179a0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
179b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
179c0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
179d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
179e0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
179f0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
17a00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17a10 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
17a20 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
17a30 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
17a40 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
17a50 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
17a60 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
17a70 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
17a80 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
17a90 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
17aa0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
17ab0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
17ac0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
17ad0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
17ae0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
17af0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
17b00 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
17b10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
17b20 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
17b30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17b40 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
17b50 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
17b60 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
17b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17b80 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
17b90 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
17ba0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
17bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
17bc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17bd0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
17be0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
17bf0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
17c00 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
17c10 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
17c20 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
17c30 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
17c40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
17c50 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
17c60 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
17c70 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
17c80 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
17c90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
17ca0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
17cb0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
17cc0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
17cd0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
17ce0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17cf0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
17d00 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
17d10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
17d20 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
17d30 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
17d40 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
17d50 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
17d60 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
17d70 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
17d80 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
17d90 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
17da0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
17db0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
17dc0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
17dd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17de0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
17df0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
17e00 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
17e10 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
17e20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17e30 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
17e40 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
17e50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
17e60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17e70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17e80 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
17e90 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
17ea0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17eb0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
17ec0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
17ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17ee0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
17ef0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17f00 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
17f10 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
17f20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
17f30 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
17f40 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
17f50 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
17f60 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
17f70 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
17f80 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
17f90 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
17fa0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17fb0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
17fc0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
17fd0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
17fe0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
17ff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18000 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
18010 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
18020 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
18030 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
18040 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
18050 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
18060 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
18070 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
18080 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
18090 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
180a0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
180b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
180c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
180d0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
180e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
180f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
18100 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
18110 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
18120 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
18130 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
18140 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
18150 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
18160 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
18170 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
18180 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
18190 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
181a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
181b0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
181c0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
181d0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
181e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
181f0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
18200 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
18210 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
18220 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
18230 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
18240 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
18250 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
18260 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
18270 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
18280 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
18290 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
182a0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
182b0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
182c0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
182d0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
182e0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
182f0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
18300 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
18310 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
18320 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18330 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
18340 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
18350 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
18360 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
18370 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
18380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18390 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
183a0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
183b0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
183c0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
183d0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
183e0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
183f0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18400 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18410 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18420 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18430 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
18440 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
18450 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18460 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18470 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
18480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
18490 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
184a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
184b0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
184c0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
184d0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
184e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
184f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18500 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
18510 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
18520 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18530 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18540 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18550 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
18560 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
18570 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18580 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18590 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
185a0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
185b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
185c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
185d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
185e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
185f0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
18600 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18610 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18630 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18640 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
18650 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18680 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
18690 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
186a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
186b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
186c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
186d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
186e0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
186f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18700 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18720 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
18730 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
18740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18750 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18770 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
18780 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
18790 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
187a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
187b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
187c0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
187d0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
187e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
187f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18810 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
18820 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
18830 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18840 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18860 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
18870 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
18880 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
188a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
188b0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
188c0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
188d0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
188e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
188f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18900 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
18910 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
18920 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18950 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
18960 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
18970 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18980 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18990 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
189a0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
189b0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
189c0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
189d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
189e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
189f0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18a00 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
18a10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18a20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18a30 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
18a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
18a50 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
18a60 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
18a70 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
18a80 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
18a90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
18aa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18ab0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
18ac0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18ad0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
18ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
18af0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
18b00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18b10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18b20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
18b30 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
18b40 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
18b50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18b60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18b70 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
18b80 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
18b90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18ba0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
18bb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18bc0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
18bd0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
18be0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
18bf0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18c00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18c10 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
18c20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
18c30 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
18c40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18c50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c60 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
18c70 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
18c80 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
18c90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18ca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18cb0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
18cc0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
18cd0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
18ce0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18cf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d00 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
18d10 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
18d20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18d30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d50 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
18d60 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
18d70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
18d80 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
18d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18da0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
18db0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
18dc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
18dd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
18de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
18df0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
18e00 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
18e10 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
18e20 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
18e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
18e40 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
18e50 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
18e60 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
18e70 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
18e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
18e90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18ea0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
18eb0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
18ec0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
18ed0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
18ee0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
18ef0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18f00 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
18f10 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
18f20 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
18f30 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
18f40 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
18f50 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
18f60 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
18f70 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
18f80 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
18f90 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
18fa0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
18fb0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
18fc0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
18fd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
18fe0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
18ff0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
19000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
19010 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
19020 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
19030 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
19040 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
19050 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
19060 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
19070 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
19080 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
19090 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
190a0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
190b0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
190c0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
190d0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
190e0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
190f0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
19100 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
19110 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
19120 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
19130 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
19140 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
19150 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19160 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19170 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
19180 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
19190 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
191a0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
191b0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
191c0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
191d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
191e0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
191f0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
19200 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
19210 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
19220 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
19230 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f  ok to run..*/.vo
19240 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
19250 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
19260 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
19270 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
19280 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
19290 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
192a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
192b0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
192c0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
192d0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
192e0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
192f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19300 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
19310 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
19320 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
19330 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
19340 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19350 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
19360 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19370 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
19380 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
19390 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
193a0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
193b0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
193c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
193d0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
193e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
193f0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
19400 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
19410 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
19420 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
19430 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
19440 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ery..**.** ^If t
19450 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19460 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
19470 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
19480 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
19490 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
194a0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
194b0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
194c0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
194d0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
194e0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
194f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
19500 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73  ress handler mus
19510 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
19520 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
19530 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
19540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19550 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
19560 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
19570 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
19580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19590 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
195a0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
195b0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
195c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
195d0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
195e0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
195f0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
19600 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
19610 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19620 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19630 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
19640 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
19650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
19660 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
19670 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
19680 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
19690 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
196a0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
196b0 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
196c0 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
196d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
196e0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
196f0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
19700 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
19710 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
19720 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19730 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
19740 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
19750 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
19760 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
19770 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
19780 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
19790 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
197a0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
197b0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
197c0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
197d0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
197e0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
197f0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
19800 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
19810 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
19820 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
19830 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
19840 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
19850 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
19860 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
19870 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
19880 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
19890 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
198a0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
198b0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
198c0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
198d0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
198e0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
198f0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
19900 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
19910 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
19920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
19930 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
19940 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
19950 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
19960 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
19970 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
19980 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
19990 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
199a0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
199b0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
199c0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
199d0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
199e0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
199f0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
19a00 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
19a10 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
19a20 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
19a30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19a40 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
19a50 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
19a60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
19a70 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
19a80 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
19a90 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
19aa0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
19ab0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
19ac0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
19ad0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
19ae0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
19af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
19b00 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
19b10 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
19b20 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
19b30 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
19b40 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
19b50 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
19b60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
19b70 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
19b80 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
19b90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
19ba0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
19bb0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
19bc0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
19bd0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
19be0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
19bf0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
19c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
19c10 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
19c20 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
19c30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
19c40 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
19c50 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
19c60 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
19c70 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
19c80 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
19c90 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
19ca0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
19cb0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
19cc0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
19cd0 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
19ce0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
19cf0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
19d00 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
19d10 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
19d20 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
19d30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
19d40 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
19d50 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
19d60 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
19d70 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
19d80 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
19d90 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
19da0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
19db0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
19dc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19dd0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
19de0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
19df0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
19e00 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
19e10 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
19e20 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
19e30 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
19e40 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
19e50 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
19e60 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
19e70 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
19e80 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
19e90 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
19ea0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
19eb0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
19ec0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
19ed0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
19ee0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
19ef0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
19f00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
19f10 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
19f20 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
19f30 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
19f40 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
19f50 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
19f60 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
19f70 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
19f80 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
19f90 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
19fa0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
19fb0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
19fc0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
19fd0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
19fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
19ff0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1a000 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1a010 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1a020 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
1a030 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
1a040 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1a050 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
1a060 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
1a070 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1a080 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1a090 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51  LLMUTEX],.** [SQ
1a0a0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1a0b0 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53  CACHE] and/or [S
1a0c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1a0d0 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  DCACHE] flags,.*
1a0e0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1a0f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1a100 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a110 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a120 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1a130 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1a140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a150 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1a160 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1a170 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1a180 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1a190 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1a1a0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1a1b0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1a1c0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1a1d0 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1a1e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1a1f0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1a200 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1a210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a220 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1a230 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1a240 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1a250 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1a260 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1a270 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1a280 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1a290 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1a2a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1a2b0 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1a2c0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1a2d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a2e0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1a2f0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1a300 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1a310 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1a320 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1a330 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1a340 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1a350 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1a360 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1a370 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1a380 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1a390 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1a3a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a3b0 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1a3c0 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1a3d0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1a3e0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1a3f0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1a400 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1a410 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1a420 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1a430 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1a440 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1a450 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1a460 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1a470 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1a480 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1a490 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1a4a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a4b0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1a4c0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1a4d0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1a4e0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1a4f0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1a500 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1a510 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1a520 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1a530 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1a540 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1a550 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1a560 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1a570 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1a580 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1a590 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1a5a0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1a5b0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1a5c0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1a5d0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1a5e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a5f0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1a600 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1a610 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1a620 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1a630 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1a640 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1a650 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1a660 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1a670 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1a680 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1a690 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a6a0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1a6b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1a6c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1a6d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1a6e0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1a6f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1a700 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1a710 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1a720 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1a730 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1a740 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1a750 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1a760 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1a770 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1a780 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1a790 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1a7a0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1a7b0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1a7c0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1a7d0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1a7e0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1a7f0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1a800 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1a810 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1a820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1a830 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1a840 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1a850 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1a860 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1a870 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1a880 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1a890 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1a8a0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1a8b0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1a8c0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1a8d0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1a8e0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1a8f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1a900 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a910 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1a920 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1a930 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a940 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a950 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a960 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a970 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1a980 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a990 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a9a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1a9b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1a9c0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1a9d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1a9e0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1a9f0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1aa00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1aa10 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1aa20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1aa30 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1aa40 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1aa50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1aa60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1aa70 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1aa80 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1aa90 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1aaa0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1aab0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1aac0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1aad0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1aae0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1aaf0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1ab00 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1ab10 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1ab20 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1ab30 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1ab40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1ab50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1ab60 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1ab70 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1ab80 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1ab90 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1aba0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1abb0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1abc0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1abd0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1abe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1abf0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1ac00 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1ac10 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1ac20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1ac30 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1ac40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1ac50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1ac60 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1ac70 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1ac80 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1ac90 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1aca0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1acb0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1acc0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1acd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1ace0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1acf0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1ad00 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1ad10 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1ad20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1ad30 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1ad40 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1ad50 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ad60 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1ad70 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ad80 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1ad90 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ada0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1adb0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1adc0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1add0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1ade0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1adf0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1ae00 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1ae10 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1ae20 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1ae30 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1ae40 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1ae50 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1ae60 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1ae70 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1ae80 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1ae90 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1aea0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1aeb0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1aec0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1aed0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1aee0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1aef0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1af00 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1af10 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1af20 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1af30 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1af40 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1af50 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1af60 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1af70 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1af80 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1af90 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1afa0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1afb0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1afc0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1afd0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1afe0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1aff0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1b000 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1b010 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1b020 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1b030 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1b040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1b050 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1b060 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1b070 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1b080 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1b090 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1b0a0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1b0b0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1b0c0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1b0d0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1b0e0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1b0f0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1b100 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1b110 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1b120 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1b130 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1b140 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1b150 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1b160 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1b170 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1b180 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1b190 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1b1a0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1b1b0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1b1c0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1b1d0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1b1e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1b1f0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b200 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1b210 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1b220 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1b230 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1b240 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1b250 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1b260 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1b270 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1b280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1b290 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1b2a0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1b2b0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1b2c0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1b2d0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1b2e0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1b2f0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1b300 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1b310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1b320 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1b330 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1b340 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1b350 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1b360 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1b370 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1b380 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1b390 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1b3a0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1b3b0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1b3c0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1b3d0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1b3e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1b3f0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1b400 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1b410 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1b420 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1b430 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1b440 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1b450 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1b460 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1b470 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1b480 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1b490 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1b4a0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1b4b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b4c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1b4d0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1b4e0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1b4f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1b500 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1b510 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1b520 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1b530 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1b540 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1b550 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1b560 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b570 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1b580 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1b590 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1b5a0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1b5b0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1b5c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b5d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1b5e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1b5f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1b600 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1b610 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1b620 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1b630 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1b640 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1b650 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1b660 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1b670 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1b680 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1b690 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1b6a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b6b0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1b6c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b6d0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1b6e0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1b6f0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1b700 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b710 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1b720 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1b730 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1b740 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1b750 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1b760 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1b770 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1b780 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1b790 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1b7a0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1b7b0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b7c0 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a  e old limit.)^.*
1b7d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1b7e0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1b7f0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1b800 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1b810 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68  ged..** ^(For th
1b820 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1b830 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1b840 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1b850 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1b860 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1b870 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  ** set by a comp
1b880 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
1b890 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
1b8a0 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  med .** [limits 
1b8b0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  | SQLITE_MAX_XYZ
1b8c0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1b8d0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1b8e0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1b8f0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1b900 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1b910 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1b920 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1b930 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1b940 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1b950 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1b960 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1b970 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
1b980 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1b990 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1b9a0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1b9b0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1b9c0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1b9d0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1b9e0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1b9f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1ba00 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1ba10 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1ba20 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1ba30 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1ba40 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
1ba50 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1ba60 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1ba70 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1ba80 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1ba90 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1baa0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1bab0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1bac0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1bad0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1bae0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1baf0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1bb00 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1bb10 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1bb20 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1bb30 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1bb40 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1bb50 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1bb60 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1bb70 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1bb80 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1bb90 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1bba0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1bbb0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1bbc0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1bbd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1bbe0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1bbf0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1bc00 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1bc10 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1bc20 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1bc30 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1bc40 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1bc50 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1bc60 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1bc70 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1bc80 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1bc90 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1bca0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1bcb0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1bcc0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1bcd0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1bce0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1bcf0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1bd00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bd10 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1bd20 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1bd30 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1bd40 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1bd50 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1bd60 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1bd70 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1bd80 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1bd90 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1bda0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1bdb0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1bdc0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1bdd0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1bde0 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1bdf0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1be00 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1be10 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1be20 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1be30 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1be40 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1be50 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1be60 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1be70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1be80 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1be90 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1bea0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1beb0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1bec0 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a   row.<dd>)^.**.*
1bed0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1bee0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1bef0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1bf00 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1bf10 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1bf20 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
1bf30 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1bf40 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1bf50 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1bf60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1bf70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1bf80 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1bf90 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1bfa0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1bfb0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
1bfc0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1bfd0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1bfe0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1bff0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1c000 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1c010 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c020 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c030 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1c040 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c050 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1c060 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1c070 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1c080 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c090 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1c0a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1c0b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c0c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c0d0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1c0e0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1c0f0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1c100 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c110 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1c120 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c130 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c140 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1c150 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1c160 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1c170 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1c180 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c190 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c1a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c1b0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1c1c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c1d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c1e0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1c1f0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
1c200 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c210 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1c220 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1c230 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c240 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1c250 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1c260 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
1c270 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c280 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1c290 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1c2a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c2b0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1c2c0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1c2d0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
1c2e0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
1c2f0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
1c300 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c310 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c320 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1c330 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c340 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1c350 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c360 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1c370 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29   be bound.</dd>)
1c380 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c390 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1c3a0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1c3b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c3c0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1c3d0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1c3e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1c3f0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1c400 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1c410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c420 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1c430 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1c440 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1c450 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1c460 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1c470 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1c480 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1c490 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1c4a0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1c4b0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1c4c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1c4d0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1c4e0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1c4f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1c500 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1c510 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1c520 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c530 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1c540 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1c550 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c560 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1c570 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1c580 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c590 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1c5a0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1c5b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c5c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c5d0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1c5e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c5f0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1c600 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1c610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c620 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1c630 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1c640 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1c650 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1c660 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1c670 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1c680 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1c690 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1c6a0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1c6b0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1c6c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1c6d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1c6e0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1c6f0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1c700 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1c710 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1c720 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1c730 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1c740 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1c750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1c760 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1c770 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1c780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c790 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1c7a0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1c7b0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1c7c0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1c7d0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1c7e0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1c7f0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1c800 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1c810 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1c820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1c830 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1c840 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1c850 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1c860 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1c870 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1c880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1c890 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1c8a0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1c8b0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1c8c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1c8d0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1c8e0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1c8f0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1c900 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1c910 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1c920 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1c930 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1c940 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1c950 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1c960 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1c970 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1c980 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1c990 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1c9a0 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1c9b0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1c9c0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1c9d0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1c9e0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1c9f0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1ca00 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1ca10 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1ca20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1ca30 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1ca40 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1ca50 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1ca60 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1ca70 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1ca80 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1ca90 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1caa0 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1cab0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1cac0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1cad0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1cae0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1caf0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1cb00 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1cb10 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1cb20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1cb30 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1cb40 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1cb50 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1cb60 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1cb70 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1cb80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1cb90 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1cba0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1cbb0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1cbc0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1cbd0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1cbe0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1cbf0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1cc00 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1cc10 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1cc20 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1cc30 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1cc40 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1cc50 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1cc60 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1cc70 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1cc80 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1cc90 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1cca0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1ccb0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1ccc0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1ccd0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1cce0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1ccf0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1cd00 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1cd10 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1cd20 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1cd30 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1cd40 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1cd50 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1cd60 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1cd70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1cd80 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1cd90 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1cda0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1cdb0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1cdc0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1cdd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1cde0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1cdf0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1ce00 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1ce10 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1ce20 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1ce30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ce40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ce50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ce60 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1ce70 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1ce80 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1ce90 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1cea0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1ceb0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1cec0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1ced0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1cee0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1cef0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1cf00 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1cf10 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1cf20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1cf30 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1cf40 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1cf50 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1cf60 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1cf70 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1cf80 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1cf90 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1cfa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1cfb0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1cfc0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1cfd0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1cfe0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1cff0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1d000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1d010 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1d020 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1d030 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1d040 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1d050 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1d060 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d070 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1d080 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1d090 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1d0a0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1d0b0 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20   it again.  ^If 
1d0c0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1d0d0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1d0e0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1d0f0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1d100 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1d110 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d120 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1d130 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1d140 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1d150 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1d160 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1d170 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1d180 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1d190 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1d1a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1d1b0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1d1c0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1d1d0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1d1e0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1d1f0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1d200 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1d210 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1d220 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1d230 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1d240 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1d250 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1d260 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1d270 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1d280 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1d290 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1d2a0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1d2b0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1d2c0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1d2d0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1d2e0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1d2f0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1d300 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1d310 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1d320 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1d330 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1d340 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1d350 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1d360 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1d370 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1d380 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1d390 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1d3a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1d3b0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1d3c0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1d3d0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1d3e0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1d3f0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1d400 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1d410 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1d420 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1d430 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1d440 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  f the value of a
1d450 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
1d460 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
1d470 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
1d480 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67  e might.** chang
1d490 65 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  e the query plan
1d4a0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1d4b0 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  , then the state
1d4c0 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61  ment may be.** a
1d4d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1d4e0 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20 74  ompiled (as if t
1d4f0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 20  here had been a 
1d500 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f  schema change) o
1d510 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20  n the first .** 
1d520 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d530 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
1d540 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68  any change to th
1d550 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  e .** [sqlite3_b
1d560 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
1d570 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72  ngs] of the [par
1d580 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c  ameter]. .** </l
1d590 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1d5a0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1d5b0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1d5c0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1d5d0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1d5e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1d5f0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1d600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1d610 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1d620 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1d630 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1d640 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1d650 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1d660 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1d670 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1d680 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1d690 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d6a0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1d6b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1d6c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1d6d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1d6e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1d6f0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1d700 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d710 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1d720 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d730 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1d740 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1d750 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1d760 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1d770 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1d780 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1d790 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1d7a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1d7b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1d7c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1d7d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1d7e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1d7f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1d800 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1d810 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1d820 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1d830 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1d840 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d850 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1d860 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1d870 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1d880 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1d890 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1d8a0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1d8b0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1d8c0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1d8d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1d8e0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1d8f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1d900 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1d910 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1d920 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1d930 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1d940 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1d950 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1d960 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1d970 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1d980 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1d990 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d9a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1d9b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d9c0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1d9d0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1d9e0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1d9f0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1da00 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1da10 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1da20 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1da30 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1da40 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1da50 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1da60 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1da70 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1da80 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1da90 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1daa0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1dab0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1dac0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1dad0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1dae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1daf0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1db00 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1db10 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1db20 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1db30 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1db40 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1db50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1db60 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1db70 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1db80 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1db90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dba0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1dbb0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1dbc0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1dbd0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1dbe0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1dbf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dc00 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1dc10 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1dc20 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1dc30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1dc40 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1dc50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1dc60 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1dc70 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1dc80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1dc90 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1dca0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1dcb0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1dcc0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1dcd0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1dce0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1dcf0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1dd00 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
1dd10 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1dd20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1dd30 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1dd40 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1dd50 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1dd60 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1dd70 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1dd80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1dd90 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1dda0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1ddb0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1ddc0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1ddd0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1dde0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ddf0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1de00 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1de10 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1de20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1de30 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1de40 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1de50 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1de60 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1de70 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1de80 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1de90 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1dea0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1deb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1dec0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1ded0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1dee0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1def0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1df00 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1df10 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1df20 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1df30 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1df40 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1df50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1df60 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1df70 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1df80 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1df90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1dfa0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1dfb0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1dfc0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1dfd0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1dfe0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1dff0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1e000 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1e010 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1e020 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1e030 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1e040 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1e050 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1e060 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1e070 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1e080 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1e090 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1e0a0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1e0b0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1e0c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1e0d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1e0e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1e0f0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1e100 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1e110 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1e120 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1e130 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1e140 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e150 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1e160 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1e170 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1e180 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1e190 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1e1a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e1b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e1c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1e1d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1e1e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1e1f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e200 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1e210 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1e220 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1e230 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1e240 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1e250 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1e260 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1e270 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
1e280 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e290 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1e2a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e2b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1e2c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1e2d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e2e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1e2f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1e300 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1e310 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1e320 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1e330 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1e340 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1e350 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1e360 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1e370 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1e380 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1e390 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e3a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1e3b0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1e3c0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1e3d0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1e3e0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1e3f0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1e400 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
1e410 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1e420 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1e430 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1e440 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1e450 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1e460 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
1e470 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1e480 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1e490 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1e4a0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1e4b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1e4c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1e4d0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1e4e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1e4f0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1e500 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1e510 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1e520 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1e530 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1e540 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1e550 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1e560 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1e570 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1e580 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1e590 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1e5a0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1e5b0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1e5c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1e5d0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1e5e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1e5f0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1e600 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1e610 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1e620 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1e630 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1e640 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1e650 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
1e660 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
1e670 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
1e680 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
1e690 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
1e6a0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
1e6b0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
1e6c0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
1e6d0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
1e6e0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
1e6f0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
1e700 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
1e710 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1e720 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
1e730 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
1e740 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
1e750 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
1e760 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
1e770 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
1e780 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
1e790 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
1e7a0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
1e7b0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
1e7c0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
1e7d0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
1e7e0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
1e7f0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
1e800 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
1e810 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
1e820 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
1e830 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
1e840 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
1e850 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20  ic identifer.)^ 
1e860 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
1e870 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1e880 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1e890 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1e8a0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1e8b0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1e8c0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1e8d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1e8e0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1e8f0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1e900 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1e910 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1e920 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1e930 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1e940 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1e950 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1e960 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1e970 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1e980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e990 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e9a0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1e9b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1e9c0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
1e9d0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1e9e0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
1e9f0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
1ea00 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
1ea10 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
1ea20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
1ea30 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
1ea40 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
1ea50 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
1ea60 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
1ea70 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
1ea80 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
1ea90 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
1eaa0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
1eab0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
1eac0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1ead0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1eae0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1eaf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1eb00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1eb10 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1eb20 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
1eb30 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1eb40 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1eb50 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
1eb60 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1eb70 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1eb80 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1eb90 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1eba0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1ebb0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1ebc0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1ebd0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1ebe0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
1ebf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
1ec00 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
1ec10 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
1ec20 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
1ec30 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1ec40 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1ec50 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1ec60 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1ec70 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
1ec80 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1ec90 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1eca0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1ecb0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
1ecc0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
1ecd0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1ece0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
1ecf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
1ed00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1ed10 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1ed20 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1ed30 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1ed40 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1ed50 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1ed60 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1ed70 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
1ed80 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1ed90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1eda0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1edb0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1edc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1edd0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1ede0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1edf0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1ee00 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1ee10 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1ee20 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49  shed with it. ^I
1ee30 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1ee40 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1ee50 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1ee60 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1ee70 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1ee80 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1ee90 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1eea0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1eeb0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1eec0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1eed0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
1eee0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1eef0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1ef00 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1ef10 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1ef20 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1ef30 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1ef40 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1ef50 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1ef60 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1ef70 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1ef80 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
1ef90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1efa0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1efb0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1efc0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1efd0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1efe0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
1eff0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1f000 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1f010 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1f020 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1f030 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
1f040 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1f050 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1f060 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1f070 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1f080 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
1f090 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
1f0a0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
1f0b0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
1f0c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1f0d0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
1f0e0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1f0f0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
1f100 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
1f110 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
1f120 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
1f130 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
1f140 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
1f150 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f160 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1f170 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1f180 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
1f190 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f1a0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
1f1b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f1c0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
1f1d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f1e0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1f1f0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
1f200 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
1f210 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
1f220 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
1f230 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
1f240 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
1f250 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
1f260 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
1f270 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
1f280 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
1f290 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
1f2a0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
1f2b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f2c0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
1f2d0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
1f2e0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1f2f0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1f300 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1f310 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
1f320 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
1f330 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f340 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1f350 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
1f360 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f370 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
1f380 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
1f390 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
1f3a0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
1f3b0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
1f3c0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
1f3d0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
1f3e0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
1f3f0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
1f400 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
1f410 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
1f420 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
1f430 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f450 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1f460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1f470 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1f480 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1f490 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f4a0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
1f4b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1f4c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1f4d0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1f4e0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1f4f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1f500 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1f510 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1f520 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1f530 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f540 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1f550 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1f560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f570 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1f580 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1f590 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1f5a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1f5b0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1f5c0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1f5d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1f5e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f5f0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1f600 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1f610 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1f620 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1f630 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f640 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1f650 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1f660 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1f670 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1f680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f690 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1f6a0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1f6b0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1f6c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f6d0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1f6e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f6f0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1f700 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
1f710 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
1f720 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
1f730 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
1f740 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
1f750 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
1f760 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
1f770 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1f780 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
1f790 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
1f7a0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
1f7b0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
1f7c0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
1f7d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
1f7e0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
1f7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f800 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
1f810 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
1f820 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
1f830 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
1f840 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
1f850 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
1f860 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
1f870 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
1f880 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
1f890 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
1f8a0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
1f8b0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
1f8c0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
1f8d0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
1f8e0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
1f8f0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
1f900 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
1f910 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
1f920 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
1f930 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f940 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f950 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1f960 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f970 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f980 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1f990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f9a0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1f9b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1f9c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1f9d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1f9e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f9f0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
1fa00 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
1fa10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fa20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fa30 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
1fa40 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
1fa50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
1fa60 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
1fa70 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
1fa80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1fa90 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
1faa0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
1fab0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
1fac0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1fad0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
1fae0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
1faf0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
1fb00 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1fb10 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1fb20 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
1fb30 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
1fb40 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
1fb50 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
1fb60 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
1fb70 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
1fb80 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
1fb90 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
1fba0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1fbb0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1fbc0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1fbd0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1fbe0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
1fbf0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
1fc00 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
1fc10 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
1fc20 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
1fc30 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1fc40 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
1fc50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
1fc60 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
1fc70 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
1fc80 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
1fc90 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
1fca0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
1fcb0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
1fcc0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
1fcd0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
1fce0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
1fcf0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
1fd00 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
1fd10 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
1fd20 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
1fd30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fd40 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
1fd50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1fd60 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
1fd70 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1fd80 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1fd90 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1fda0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fdb0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
1fdc0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1fdd0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1fde0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
1fdf0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1fe00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1fe10 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fe20 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
1fe30 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
1fe40 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
1fe50 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
1fe60 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
1fe70 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1fe80 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
1fe90 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
1fea0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
1feb0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
1fec0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
1fed0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
1fee0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1fef0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1ff00 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
1ff10 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
1ff20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1ff30 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1ff40 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
1ff50 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1ff60 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1ff70 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1ff80 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1ff90 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1ffa0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1ffb0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1ffc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ffd0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1ffe0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1fff0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
20000 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
20010 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
20020 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
20030 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
20040 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20050 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
20060 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20070 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
20080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20090 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
200a0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
200b0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
200c0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
200d0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
200e0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
200f0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
20100 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
20110 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
20120 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
20130 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
20140 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
20150 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
20160 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
20170 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
20180 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
20190 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
201a0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
201b0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
201c0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
201d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
201e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
201f0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
20200 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
20210 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
20220 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
20230 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
20240 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
20250 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20260 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
20270 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
20280 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
20290 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
202a0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
202b0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
202c0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
202d0 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ])..*/.int sqlit
202e0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
202f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
20300 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
20310 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
20320 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
20330 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
20340 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
20350 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
20360 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
20370 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
20380 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
20390 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
203a0 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
203b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
203c0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
203d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
203e0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
203f0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
20400 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
20410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
20420 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
20430 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
20440 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
20450 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
20460 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20470 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
20480 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
20490 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
204a0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
204b0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
204c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
204d0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
204e0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
204f0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
20500 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
20510 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
20520 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
20530 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
20540 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
20550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
20560 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
20570 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20580 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
20590 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
205a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
205b0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
205c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
205d0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
205e0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
205f0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20600 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
20610 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
20620 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
20630 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
20640 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
20650 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
20660 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
20670 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
20680 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
20690 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
206a0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
206b0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
206c0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
206d0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
206e0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
206f0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
20700 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
20710 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
20720 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
20730 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
20740 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
20750 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
20760 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
20770 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
20780 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
20790 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
207a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
207b0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
207c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
207d0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
207e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
207f0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
20800 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
20810 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
20820 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
20830 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
20840 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
20850 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
20860 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
20870 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
20880 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
20890 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
208a0 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
208b0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
208c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
208d0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
208e0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
208f0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
20900 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
20910 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
20920 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
20930 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
20940 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
20950 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
20960 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
20970 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
20980 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
20990 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
209a0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
209b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
209c0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
209d0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
209e0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
209f0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
20a00 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
20a10 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
20a20 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
20a30 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
20a40 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
20a50 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
20a60 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
20a70 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
20a80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
20a90 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
20aa0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
20ab0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
20ac0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
20ad0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
20ae0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
20af0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
20b00 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
20b10 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
20b20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
20b30 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
20b40 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
20b50 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
20b60 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
20b70 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
20b80 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
20b90 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
20ba0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
20bb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20bc0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
20bd0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
20be0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
20bf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
20c00 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
20c10 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
20c20 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
20c30 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
20c40 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
20c50 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
20c60 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
20c70 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
20c80 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
20c90 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
20ca0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
20cb0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
20cc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
20cd0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
20ce0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
20cf0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
20d00 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
20d10 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
20d20 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
20d30 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
20d40 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
20d50 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
20d60 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
20d70 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
20d80 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
20d90 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
20da0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
20db0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
20dc0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
20dd0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
20de0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
20df0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
20e00 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
20e10 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
20e20 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
20e30 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
20e40 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
20e50 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
20e60 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
20e70 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
20e80 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
20e90 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
20ea0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
20eb0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
20ec0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20ed0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
20ee0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
20ef0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
20f00 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
20f10 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
20f20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
20f30 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
20f40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20f50 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
20f60 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
20f70 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
20f80 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
20f90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20fa0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
20fb0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
20fc0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
20fd0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
20fe0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
20ff0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
21000 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
21010 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21020 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
21030 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21040 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
21050 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21060 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
21070 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
21080 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
21090 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
210a0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
210b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
210c0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
210d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
210e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
210f0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
21100 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21110 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
21120 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21130 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
21140 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21150 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21160 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
21170 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
21180 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
21190 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
211a0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
211b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
211c0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
211d0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
211e0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
211f0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
21200 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
21210 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
21220 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
21230 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
21240 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
21250 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
21260 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
21270 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
21280 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
21290 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
212a0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
212b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
212c0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
212d0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
212e0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
212f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
21300 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
21310 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21320 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
21330 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
21340 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
21350 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
21360 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
21370 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
21380 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
21390 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
213a0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
213b0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
213c0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
213d0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
213e0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
213f0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
21400 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
21410 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
21420 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
21430 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
21440 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
21450 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
21460 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
21470 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
21480 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
21490 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
214a0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
214b0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
214c0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
214d0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
214e0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
214f0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
21500 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
21510 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
21520 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
21530 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
21540 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
21550 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
21560 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
21570 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
21580 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
21590 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
215a0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
215b0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
215c0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
215d0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
215e0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
215f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21600 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
21610 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21620 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21630 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
21640 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21650 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
21660 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
21670 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
21680 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
21690 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
216a0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
216b0 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
216c0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
216d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
216e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
216f0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
21700 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
21710 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
21720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
21730 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
21740 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
21750 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
21760 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
21770 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
21780 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
21790 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
217a0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
217b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
217c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
217d0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
217e0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
217f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
21800 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
21810 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
21820 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
21830 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21840 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21850 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
21860 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
21870 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
21880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21890 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
218a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
218b0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
218c0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
218d0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
218e0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
218f0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
21900 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
21910 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
21920 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
21930 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
21940 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
21950 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
21960 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
21970 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
21980 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
21990 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
219a0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
219b0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
219c0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
219d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
219e0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
219f0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
21a00 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
21a10 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
21a20 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
21a30 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
21a40 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
21a50 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
21a60 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
21a70 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
21a80 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
21a90 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
21aa0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
21ab0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
21ac0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
21ad0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
21ae0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
21af0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
21b00 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
21b10 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
21b20 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
21b30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21b40 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
21b50 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
21b60 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
21b70 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
21b80 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
21b90 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
21ba0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
21bb0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
21bc0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
21bd0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
21be0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
21bf0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
21c00 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
21c10 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
21c20 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
21c30 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
21c40 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
21c50 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
21c60 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
21c70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21c80 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
21c90 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
21ca0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
21cb0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
21cc0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
21cd0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
21ce0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
21cf0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
21d00 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
21d10 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
21d20 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
21d30 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
21d40 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
21d50 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
21d60 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
21d70 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
21d80 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
21d90 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
21da0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
21db0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
21dc0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
21dd0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
21de0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
21df0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
21e00 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
21e10 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
21e20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
21e30 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
21e40 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
21e50 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
21e60 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
21e70 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
21e80 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
21e90 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
21ea0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
21eb0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
21ec0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
21ed0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
21ee0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
21ef0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
21f00 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
21f10 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
21f20 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
21f30 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
21f40 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
21f50 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
21f60 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
21f70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
21f80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
21f90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
21fa0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21fb0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
21fc0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
21fd0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
21fe0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
21ff0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
22000 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
22010 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
22020 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
22030 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
22040 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
22050 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
22060 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
22070 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
22080 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
22090 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
220a0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
220b0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
220c0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
220d0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
220e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
220f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
22100 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
22110 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
22120 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
22130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22140 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
22150 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
22160 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
22170 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
22180 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
22190 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
221a0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
221b0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
221c0 31 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72  1, it was requir
221d0 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69  ed.** after sqli
221e0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
221f0 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68  ned anything oth
22200 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22210 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71  ROW] that.** [sq
22220 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62  lite3_reset()] b
22230 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
22240 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
22250 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
22260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
22270 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f   Failure to invo
22280 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
22290 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79  t()] in this way
222a0 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74   would.** result
222b0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
222c0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
222d0 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  om sqlite3_step(
222e0 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a  ).  But after.**
222f0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
22300 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
22310 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20  ) began calling 
22320 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22330 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ] .** automatica
22340 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
22350 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20  umstance rather 
22360 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
22370 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
22380 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79   .**.** <b>Goofy
22390 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
223a0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
223b0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
223c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
223d0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
223e0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
223f0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
22400 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
22410 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
22420 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
22430 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
22440 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
22450 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
22460 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
22470 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
22480 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
22490 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
224a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
224b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
224c0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
224d0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
224e0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
224f0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
22500 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
22510 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
22520 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
22530 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
22540 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
22550 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
22560 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
22570 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
22580 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22590 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
225a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
225b0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
225c0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
225d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
225e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
225f0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
22600 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
22610 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
22620 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
22630 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
22640 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
22650 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
22660 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
22670 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
22680 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
22690 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
226a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
226b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
226c0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
226d0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
226e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
226f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
22700 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  P) the number of
22710 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
22720 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
22730 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
22740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
22750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
22760 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
22770 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22790 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
227a0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
227b0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
227c0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
227d0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
227e0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
227f0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
22800 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
22810 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
22820 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
22830 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
22840 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
22850 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
22860 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
22870 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
22880 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
22890 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
228a0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
228b0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
228c0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
228d0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
228e0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
228f0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
22900 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
22910 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
22920 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
22930 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
22940 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
22950 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
22960 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
22970 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22980 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
22990 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
229a0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
229b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
229c0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
229e0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
229f0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
22a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
22a10 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
22a20 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
22a30 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
22a40 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
22a50 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
22a60 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
22a70 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
22a80 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
22a90 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
22aa0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
22ab0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
22ac0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
22ad0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
22ae0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
22af0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
22b00 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
22b10 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
22b20 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
22b30 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
22b40 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
22b50 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
22b60 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
22b70 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
22b80 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
22b90 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
22ba0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
22bb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22bc0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
22bd0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
22be0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
22bf0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
22c00 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
22c10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22c20 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
22c30 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
22c40 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
22c50 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
22c60 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
22c70 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
22c80 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
22c90 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
22ca0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
22cb0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
22cc0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
22cd0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
22ce0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22cf0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
22d00 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
22d10 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
22d20 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
22d30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
22d40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
22d50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
22d60 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
22d70 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
22d80 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
22d90 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
22da0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
22db0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
22dc0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
22dd0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
22de0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
22df0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
22e00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22e10 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
22e20 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
22e30 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
22e40 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
22e50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22e60 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
22e70 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
22e80 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
22e90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
22ea0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
22eb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22ec0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
22ed0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22ee0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
22ef0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
22f00 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
22f10 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
22f20 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
22f30 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
22f40 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
22f50 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
22f60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22f70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
22f80 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
22f90 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
22fa0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
22fb0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
22fc0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
22fd0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
22fe0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
22ff0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
23000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
23010 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
23020 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
23030 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
23040 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
23050 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
23060 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
23070 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
23080 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
23090 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
230a0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
230b0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
230c0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
230d0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
230e0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
230f0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
23100 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
23110 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23120 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
23130 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
23140 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
23150 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
23160 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
23170 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
23180 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
23190 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
231a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
231b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
231c0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
231d0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
231e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
231f0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
23200 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
23210 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
23220 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
23230 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
23240 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
23250 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
23260 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
23270 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
23280 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
23290 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
232a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
232b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
232c0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
232d0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
232e0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
232f0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
23300 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23310 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
23320 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
23330 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
23340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23350 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
23360 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
23370 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
23380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23390 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
233a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
233b0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
233c0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
233d0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
233e0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
233f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
23400 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
23410 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
23420 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
23430 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
23440 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
23450 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
23460 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
23470 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
23480 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
23490 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
234a0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
234b0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
234c0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
234d0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
234e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
234f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23500 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
23510 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
23520 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
23530 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
23540 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
23550 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
23560 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
23570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23580 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
23590 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
235a0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
235b0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
235c0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
235d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
235e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
235f0 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
23600 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
23610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23620 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
23630 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
23640 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
23650 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
23660 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
23670 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  * ^The zero term
23680 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
23690 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
236a0 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ount..**.** ^The
236b0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
236c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
236d0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
236e0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
236f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23700 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
23710 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23720 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
23730 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
23740 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
23750 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
23760 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
23770 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
23780 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
23790 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
237a0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
237b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
237c0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
237d0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
237e0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
237f0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
23800 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
23810 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
23820 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
23830 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
23840 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
23850 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
23860 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
23870 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
23880 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
23890 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
238a0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
238b0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
238c0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
238d0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
238e0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
238f0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
23900 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
23910 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
23920 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
23930 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
23940 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
23950 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
23960 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
23970 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
23980 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
23990 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
239a0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
239b0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
239c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
239d0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
239e0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
239f0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
23a00 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
23a10 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
23a20 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
23a30 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
23a40 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
23a50 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
23a60 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
23a70 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
23a80 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
23a90 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
23aa0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23ab0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
23ac0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23ad0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23ae0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23af0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
23b00 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23b10 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23b20 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
23b30 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
23b40 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
23b50 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
23b60 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
23b70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23b80 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
23b90 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
23ba0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
23bb0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
23bc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
23bd0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
23be0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
23bf0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
23c00 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
23c10 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
23c20 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
23c30 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
23c40 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23c50 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
23c60 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
23c70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
23c80 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
23c90 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
23ca0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
23cb0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23cc0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
23cd0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
23ce0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
23cf0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
23d00 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
23d10 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
23d20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
23d30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
23d40 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
23d50 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
23d60 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23d70 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
23d80 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
23d90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
23da0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
23db0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
23dc0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
23dd0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
23de0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
23df0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23e00 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
23e10 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
23e20 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
23e30 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
23e40 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
23e50 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
23e60 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
23e70 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
23e80 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
23e90 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
23ea0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
23eb0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
23ec0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
23ed0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
23ee0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
23ef0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
23f00 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
23f10 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
23f20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
23f30 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
23f40 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
23f50 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
23f60 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
23f70 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  mers..**.** ^Not
23f80 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
23f90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
23fa0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
23fb0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
23fc0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
23fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
23fe0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
23ff0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
24000 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
24010 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
24020 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
24030 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73  * ^(Type convers
24040 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
24050 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
24060 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
24070 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
24080 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
24090 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
240a0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
240b0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
240c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
240d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
240e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
240f0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
24100 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
24110 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
24120 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
24130 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
24140 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
24150 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
24160 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
24170 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
24180 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
24190 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
241a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
241b0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
241c0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
241d0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
241e0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
241f0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
24200 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
24210 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
24220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24230 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
24240 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
24250 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
24260 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
24270 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
24280 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
24290 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
242a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  >)^.**.** ^Conve
242b0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
242c0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
242d0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
242e0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
242f0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
24300 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
24310 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
24320 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
24330 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
24340 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
24350 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
24360 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
24370 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
24380 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
24390 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
243a0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
243b0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
243c0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
243d0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
243e0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
243f0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
24400 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
24410 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
24420 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73  *.** ^(The safes
24430 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
24440 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
24450 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
24460 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
24470 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
24480 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
24490 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
244a0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
244b0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
244c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
244d0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
244e0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
244f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
24500 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
24510 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
24520 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
24530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24540 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
24550 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24560 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
24570 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
24580 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
24590 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
245a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
245b0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
245c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
245d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
245e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
245f0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
24600 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
24610 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
24620 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
24630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24640 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
24650 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24660 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
24670 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
24680 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
24690 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
246a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
246b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
246c0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
246d0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
246e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
246f0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
24700 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
24710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24720 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
24730 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
24740 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
24750 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
24760 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
24770 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
24780 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
24790 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
247a0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
247b0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
247c0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
247d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
247e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
247f0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
24800 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
24810 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
24820 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
24830 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
24840 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
24850 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
24860 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
24870 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
24880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24890 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
248a0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
248b0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
248c0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
248d0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
248e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
248f0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
24900 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
24910 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
24920 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
24930 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
24940 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
24950 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
24960 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
24970 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
24980 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
24990 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
249a0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
249b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
249c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
249d0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
249e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
249f0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
24a00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24a10 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
24a20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24a30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24a40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
24a50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24a60 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
24a70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24a80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24a90 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
24aa0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
24ab0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
24ac0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24ad0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24ae0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
24af0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24b00 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
24b10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24b20 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
24b30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24b40 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
24b50 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
24b60 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
24b70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24b80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24ba0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
24bb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
24bc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
24bd0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
24be0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24bf0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
24c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
24c10 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
24c20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
24c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24c40 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
24c50 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
24c60 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
24c70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24c80 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
24c90 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
24ca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24cb0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
24cc0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
24cd0 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
24ce0 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
24cf0 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
24d00 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
24d10 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66  is returned. ^If
24d20 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
24d30 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
24d40 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65  ed then an.** [e
24d50 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
24d60 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
24d70 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
24d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
24d90 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
24da0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
24db0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
24dc0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
24dd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24de0 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69  nt].  ^If the vi
24df0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
24e00 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
24e10 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
24e20 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
24e30 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
24e40 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
24e50 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
24e60 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
24e70 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
24e80 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d  rupt]..** ^Incom
24e90 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
24ea0 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
24eb0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
24ec0 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
24ed0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
24ee0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
24ef0 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
24f00 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
24f10 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
24f20 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ABORT]..*/.int s
24f30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24f50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24f60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
24f70 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24f80 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
24f90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
24fa0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
24fb0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
24fc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24fd0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
24fe0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
24ff0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
25000 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
25010 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
25020 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
25030 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
25040 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
25050 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
25060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25070 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
25080 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
25090 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
250a0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
250b0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
250c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
250d0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
250e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
250f0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
25100 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
25110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25120 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
25130 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
25140 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
25150 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
25160 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25170 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
25180 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
25190 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
251a0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
251b0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
251c0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
251d0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
251e0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
251f0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
25200 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
25210 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25220 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
25230 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
25240 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25250 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25260 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
25270 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
25280 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
25290 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
252a0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
252b0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
252c0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
252d0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
252e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
252f0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
25300 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
25310 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
25320 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
25330 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25340 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
25350 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25360 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
25370 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
25380 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
25390 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
253a0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
253b0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
253c0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
253d0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
253e0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
253f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25400 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25410 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
25420 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25430 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25440 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
25450 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74  }.**.** ^These t
25460 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
25470 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
25480 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
25490 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
254a0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
254b0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
254c0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
254d0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
254e0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
254f0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
25500 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25510 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
25520 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
25530 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
25540 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
25550 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
25560 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
25570 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
25580 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
25590 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
255a0 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
255b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
255c0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
255d0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
255e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
255f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  )..**.** ^The fi
25600 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
25610 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
25620 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
25630 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
25640 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
25650 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
25660 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
25670 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
25680 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
25690 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
256a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
256b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
256c0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
256d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
256e0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
256f0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
25700 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25710 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
25720 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25730 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
25740 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
25750 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
25760 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
25770 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
25780 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a  , exclusive of.*
25790 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  * the zero-termi
257a0 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
257b0 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
257c0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
257d0 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
257e0 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74  acters.  ^Any at
257f0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
25800 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
25810 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
25820 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
25830 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
25840 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
25850 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
25860 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
25870 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
25880 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
25890 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
258a0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
258b0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
258c0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
258d0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
258e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
258f0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
25900 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
25910 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
25920 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
25930 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
25940 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
25950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
25960 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
25970 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
25980 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
25990 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
259a0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
259b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
259c0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
259d0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
259e0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
259f0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
25a00 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
25a10 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
25a20 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
25a30 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
25a40 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
25a50 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
25a60 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
25a70 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
25a80 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
25a90 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
25aa0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
25ab0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
25ac0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
25ad0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
25ae0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
25af0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
25b00 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
25b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
25b20 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
25b30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25b40 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
25b50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
25b60 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
25b70 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
25b80 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
25b90 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
25ba0 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
25bb0 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
25bc0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
25bd0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25be0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
25bf0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
25c00 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
25c10 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
25c20 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
25c30 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
25c40 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
25c50 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
25c60 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
25c70 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
25c80 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
25c90 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
25ca0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
25cb0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25cc0 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
25cd0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
25ce0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
25cf0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
25d00 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
25d10 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
25d20 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
25d30 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
25d40 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
25d50 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
25d60 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
25d70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .)^.**.** The se
25d80 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
25d90 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
25da0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
25db0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
25dc0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
25dd0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
25de0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
25df0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
25e00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
25e10 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
25e20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
25e30 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
25e40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
25e50 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
25e60 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
25e70 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
25e80 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
25e90 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
25ea0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
25eb0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
25ec0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
25ed0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
25ee0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
25ef0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
25f00 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
25f10 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
25f20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
25f30 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
25f40 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
25f50 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
25f60 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
25f70 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  tion callbacks..
25f80 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
25f90 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
25fa0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
25fb0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
25fc0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
25fd0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
25fe0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
25ff0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
26000 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
26010 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
26020 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
26030 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
26040 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
26050 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
26060 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
26070 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
26080 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
26090 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
260a0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
260b0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
260c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
260d0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
260e0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
260f0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
26100 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26110 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
26120 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
26130 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
26140 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
26150 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
26160 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
26170 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
26180 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
26190 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
261a0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
261b0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
261c0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
261d0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
261e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
261f0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
26200 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
26210 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
26220 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
26230 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
26240 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
26250 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
26260 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
26270 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
26280 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
26290 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
262a0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
262b0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
262c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
262d0 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ns..** ^The firs
262e0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
262f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
26300 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
26310 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
26320 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
26330 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
26340 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26350 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
26360 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53  same name..** ^S
26370 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
26380 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26390 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
263a0 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
263b0 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
263c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
263d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
263e0 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
263f0 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
26400 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
26410 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
26420 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
26430 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
26440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26450 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
26460 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
26470 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
26480 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
26490 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
264a0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
264b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
264c0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
264d0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
264e0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
264f0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
26500 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
26510 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
26520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26530 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
26540 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
26550 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
26560 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
26570 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
26580 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
26590 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
265a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
265b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
265c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
265d0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
265e0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
265f0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
26600 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
26610 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
26620 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
26630 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26640 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
26650 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
26660 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
26670 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
26680 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
26690 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
266a0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
266b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
266c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
266d0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
266e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
266f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26700 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
26710 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
26720 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
26730 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
26740 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
26750 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
26760 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
26770 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
26780 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
26790 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
267a0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
267b0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
267c0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
267d0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
267e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
267f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26800 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
26810 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
26820 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
26830 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
26840 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
26850 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
26860 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
26870 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
26880 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26890 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
268a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
268b0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
268c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
268d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
268e0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
268f0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
26900 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
26910 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
26920 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
26930 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
26940 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
26950 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
26960 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
26970 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
26980 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
26990 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
269a0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
269b0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
269c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
269d0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
269e0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
269f0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
26a00 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
26a10 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
26a20 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
26a30 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
26a40 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
26a50 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
26a60 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
26a70 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
26a80 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
26a90 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
26aa0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
26ab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26ac0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
26ad0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
26ae0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
26af0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
26b00 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
26b10 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
26b20 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
26b30 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
26b40 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
26b50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26b60 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
26b70 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
26b80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
26b90 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
26ba0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
26bb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
26bc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26bd0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
26be0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
26bf0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
26c00 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
26c10 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
26c20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
26c30 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
26c40 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
26c50 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
26c60 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
26c70 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
26c80 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
26c90 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
26ca0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
26cb0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
26cc0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
26cd0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
26ce0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
26cf0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
26d00 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
26d10 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
26d20 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
26d30 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
26d40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
26d50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26d60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
26d70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26d80 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
26d90 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
26da0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
26db0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
26dc0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
26dd0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
26de0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
26df0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
26e00 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
26e10 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
26e20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26e30 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
26e40 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
26e50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26e60 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
26e70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
26e80 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
26e90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26ea0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
26eb0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
26ec0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
26ed0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
26ee0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26ef0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
26f00 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
26f10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26f20 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
26f30 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
26f40 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
26f50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26f60 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
26f70 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
26f80 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
26f90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
26fa0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
26fb0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
26fc0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
26fd0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
26fe0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
26ff0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
27000 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
27010 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
27020 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
27030 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
27040 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
27050 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
27060 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
27070 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
27080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27090 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
270a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
270b0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
270c0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
270d0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
270e0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
270f0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
27100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27110 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
27120 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27130 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
27140 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
27150 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
27160 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
27170 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
27180 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
27190 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
271a0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
271b0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
271c0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
271d0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
271e0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
271f0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
27200 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
27210 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
27220 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
27230 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
27240 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
27250 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
27260 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
27270 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
27280 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
27290 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
272a0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
272b0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
272c0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
272d0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
272e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
272f0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
27300 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
27310 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
27320 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
27330 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
27340 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
27350 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
27360 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
27370 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
27380 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
27390 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
273a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
273b0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
273c0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
273d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
273e0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
273f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
27400 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
27410 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
27420 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
27430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
27440 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
27450 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
27460 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
27470 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
27480 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27490 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
274a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
274b0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
274c0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
274d0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
274e0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
274f0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
27500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
27510 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
27520 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27530 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
27540 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27550 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
27560 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
27570 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
27580 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
27590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
275a0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
275b0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
275c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
275d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
275e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
275f0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
27600 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
27610 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
27620 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
27630 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
27640 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27660 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27670 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27680 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
27690 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
276a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
276b0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
276c0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
276d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
276e0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
276f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
27710 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27720 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27730 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
27740 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27760 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
27770 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
27780 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
27790 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67  ementions of agg
277a0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
277b0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
277c0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
277d0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
277e0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
277f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
27800 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
27810 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27820 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
27830 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
27840 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
27850 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
27860 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
27870 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
27880 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
27890 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
278a0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
278b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
278c0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
278d0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
278e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
278f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
27900 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27910 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
27920 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
27930 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
27940 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
27950 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
27960 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27970 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
27980 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
27990 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
279a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
279b0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
279c0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
279d0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
279e0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
279f0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
27a00 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
27a10 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
27a20 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
27a30 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
27a40 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
27a50 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
27a60 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
27a70 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
27a80 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
27a90 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
27aa0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
27ab0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27ac0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
27ad0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
27ae0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
27af0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
27b00 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
27b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
27b20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27b30 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
27b40 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
27b50 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
27b60 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
27b70 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
27b80 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
27b90 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
27ba0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
27bb0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
27bc0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
27bd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27be0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
27bf0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
27c00 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
27c10 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
27c20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
27c30 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
27c40 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
27c50 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
27c60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27c70 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
27c80 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
27c90 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
27ca0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
27cb0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
27cc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
27cd0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
27ce0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
27cf0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
27d00 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
27d10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27d20 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
27d30 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
27d40 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
27d50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
27d60 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
27d70 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
27d80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
27d90 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
27da0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
27db0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
27dc0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
27dd0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
27de0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
27df0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
27e00 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
27e10 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
27e20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
27e30 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
27e40 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
27e50 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
27e60 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
27e70 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
27e80 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
27e90 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27ea0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
27eb0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
27ec0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
27ed0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
27ee0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
27ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27f00 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
27f10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27f20 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
27f30 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
27f40 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
27f50 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
27f60 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
27f70 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
27f80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27f90 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
27fa0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27fb0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
27fc0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
27fd0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
27fe0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27ff0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
28000 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
28010 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
28020 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
28030 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
28040 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
28050 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28060 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
28070 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
28080 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
28090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
280a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
280b0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
280c0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
280d0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
280e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
280f0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
28100 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
28110 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
28120 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
28130 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28140 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
28150 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
28160 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28170 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
28180 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
28190 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
281a0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
281b0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
281c0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
281d0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
281e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
281f0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
28200 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
28210 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28220 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
28230 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
28240 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
28250 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
28260 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
28270 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
28280 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
28290 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
282a0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
282b0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
282c0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
282d0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
282e0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
282f0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
28300 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
28310 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
28320 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
28330 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
28340 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
28350 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
28360 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
28370 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
28380 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
28390 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
283a0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
283b0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
283c0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
283d0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
283e0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
283f0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
28400 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
28410 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
28420 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
28430 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
28440 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
28450 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
28460 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
28470 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
28480 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
28490 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
284a0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
284b0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
284c0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
284d0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
284e0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
284f0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
28500 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
28510 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
28520 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
28530 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28540 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
28550 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
28560 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
28570 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
28580 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
28590 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
285a0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
285b0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
285c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
285d0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
285e0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
285f0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
28600 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
28610 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
28620 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
28630 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
28640 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
28650 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
28660 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
28670 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
28680 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
28690 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
286a0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
286b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
286c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
286d0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
286e0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
286f0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
28700 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
28710 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
28720 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
28730 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
28740 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
28750 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28760 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
28770 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
28780 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28790 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
287a0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
287b0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
287c0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
287d0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
287e0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
287f0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
28800 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
28810 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
28820 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
28830 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
28840 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
28850 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
28860 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
28870 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
28880 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
28890 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
288a0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
288b0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
288c0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
288d0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
288e0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
288f0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
28900 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
28910 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
28920 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
28930 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
28940 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
28950 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
28960 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
28970 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
28980 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
28990 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
289a0 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
289b0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
289c0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
289d0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
289e0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
289f0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
28a00 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
28a10 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
28a20 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
28a30 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
28a40 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
28a50 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
28a60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
28a70 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
28a80 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
28a90 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
28aa0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
28ab0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28ac0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
28ad0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
28ae0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
28af0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28b00 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
28b10 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
28b20 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
28b30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
28b40 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
28b50 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
28b60 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
28b70 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
28b80 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
28b90 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
28ba0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
28bb0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
28bc0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
28bd0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
28be0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
28bf0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
28c00 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
28c10 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
28c20 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
28c30 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
28c40 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
28c50 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
28c60 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
28c70 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
28c80 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
28c90 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
28ca0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
28cb0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
28cc0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
28cd0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
28ce0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
28cf0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
28d00 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
28d10 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28d20 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
28d30 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
28d40 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
28d50 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
28d60 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
28d70 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
28d80 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
28d90 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
28da0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
28db0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
28dc0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
28dd0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
28de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
28df0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
28e00 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28e10 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
28e20 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
28e30 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
28e40 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
28e50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
28e60 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
28e70 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
28e80 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
28e90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
28ea0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
28eb0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
28ec0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
28ed0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
28ee0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
28ef0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
28f00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28f10 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
28f20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28f30 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
28f40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28f50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
28f60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
28f70 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
28f80 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
28f90 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
28fa0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
28fb0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
28fc0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
28fd0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
28fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
28ff0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
29000 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
29010 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
29020 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
29030 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
29040 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29050 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
29060 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29070 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
29080 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29090 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
290a0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
290b0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
290c0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
290d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
290e0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
290f0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
29100 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
29110 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
29120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29130 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
29140 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
29150 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
29160 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
29170 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29180 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
29190 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
291a0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
291b0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
291c0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
291d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
291e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
291f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29200 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
29210 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29220 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
29230 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
29240 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29250 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
29260 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29270 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
29280 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
29290 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
292a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
292b0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
292c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
292d0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
292e0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
292f0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
29300 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
29310 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
29320 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
29330 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
29340 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
29350 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
29360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29370 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
29380 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
29390 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
293a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
293b0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
293c0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
293d0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
293e0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
293f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
29400 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
29410 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
29420 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
29430 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29440 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
29450 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
29460 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
29470 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
29480 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
29490 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
294a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
294b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
294c0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
294d0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
294e0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
294f0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
29500 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
29510 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
29520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29530 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
29540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29550 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
29560 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29570 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
29580 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
29590 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
295a0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
295b0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
295c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
295d0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
295e0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
295f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29600 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
29610 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29620 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
29630 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
29640 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
29650 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
29660 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
29670 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
29680 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
29690 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
296a0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
296b0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
296c0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
296d0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
296e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
296f0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
29700 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
29710 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
29720 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
29730 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
29740 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
29750 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
29760 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
29770 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
29780 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
29790 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
297a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
297b0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
297c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
297d0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
297e0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
297f0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
29800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29810 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
29820 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
29830 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
29840 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
29850 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
29860 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
29870 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
29880 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
29890 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
298a0 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
298b0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
298c0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
298d0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
298e0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
298f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
29900 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29910 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29920 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29930 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
29940 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
29950 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29960 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29970 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
29980 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
29990 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
299a0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
299b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
299c0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
299d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
299e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
299f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29a00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29a10 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
29a20 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29a30 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
29a40 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
29a50 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
29a60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29a70 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
29a80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
29a90 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
29aa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29ab0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29ac0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
29ad0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
29ae0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
29af0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29b00 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
29b10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
29b20 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
29b30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
29b40 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
29b50 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
29b60 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
29b70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29b80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
29b90 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
29ba0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
29bb0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
29bc0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
29bd0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
29be0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
29bf0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
29c00 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
29c10 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
29c20 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
29c30 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
29c40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
29c50 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
29c60 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
29c70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29c80 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
29c90 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
29ca0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
29cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29cc0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
29cd0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
29ce0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
29cf0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
29d00 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
29d10 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
29d20 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
29d30 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
29d40 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
29d50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29d60 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29d70 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
29d80 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
29d90 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
29da0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
29db0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
29dc0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
29dd0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29de0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
29df0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29e00 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
29e10 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
29e20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
29e30 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29e40 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29e50 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
29e60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29e70 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
29e80 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
29e90 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
29ea0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
29eb0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
29ec0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
29ed0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
29ee0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
29ef0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
29f00 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
29f10 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29f20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29f30 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29f40 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
29f50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
29f60 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
29f70 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
29f80 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
29f90 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
29fa0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
29fb0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
29fc0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
29fd0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
29fe0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
29ff0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
2a000 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
2a010 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
2a020 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
2a030 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2a040 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2a050 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2a060 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2a070 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2a080 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2a090 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
2a0a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2a0b0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2a0c0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
2a0d0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
2a0e0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
2a0f0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
2a100 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
2a110 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
2a120 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2a130 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
2a140 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2a150 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a160 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2a170 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2a180 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2a190 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a1a0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2a1b0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
2a1c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a1d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a1e0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
2a1f0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2a200 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2a210 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a220 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
2a230 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a240 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
2a250 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
2a260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2a270 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2a280 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2a290 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2a2a0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2a2b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a2c0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2a2d0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2a2e0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
2a2f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a300 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2a310 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2a320 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2a330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a340 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2a350 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2a360 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2a370 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2a380 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2a390 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2a3a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2a3b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2a3c0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2a3d0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2a3e0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
2a3f0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2a400 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a410 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a420 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
2a430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2a440 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2a450 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a460 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
2a470 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a480 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
2a490 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2a4a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2a4b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2a4c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a4d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
2a4e0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
2a4f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a500 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
2a510 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a520 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
2a530 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a540 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
2a550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2a560 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
2a570 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a580 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2a590 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
2a5a0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2a5b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2a5c0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
2a5d0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2a5e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a5f0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
2a600 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2a610 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a620 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
2a630 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2a640 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a650 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
2a660 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2a670 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
2a680 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a690 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
2a6a0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2a6b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a6c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a6d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2a6e0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a6f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a700 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a710 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a720 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2a730 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a740 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a750 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a760 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2a770 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2a780 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2a790 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2a7a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a7b0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2a7c0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2a7d0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2a7e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2a7f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a800 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2a810 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
2a820 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
2a830 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2a840 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2a850 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
2a860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
2a870 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
2a880 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
2a890 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2a8a0 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
2a8b0 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
2a8c0 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
2a8d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2a8e0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
2a8f0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2a900 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2a910 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2a920 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
2a930 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
2a940 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
2a950 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2a960 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a970 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2a980 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2a990 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2a9a0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2a9b0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
2a9c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2a9d0 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73  6(). ^In all cas
2a9e0 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
2a9f0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2aa00 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2aa10 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2aa20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2aa30 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
2aa40 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
2aa50 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2aa60 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
2aa70 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2aa80 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
2aa90 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
2aaa0 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
2aab0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
2aac0 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
2aad0 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
2aae0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
2aaf0 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
2ab00 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
2ab10 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
2ab20 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2ab30 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61   ^The.** third a
2ab40 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
2ab50 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
2ab60 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  F16] to indicate
2ab70 20 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e   that the routin
2ab80 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69  e.** expects poi
2ab90 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d  nters to be UTF-
2aba0 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  16 strings in th
2abb0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2abc0 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61  der, or the.** a
2abd0 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b  rgument can be [
2abe0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2abf0 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20  GNED] if the.** 
2ac00 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
2ac10 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
2ac20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
2ac30 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
2ac40 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
2ac50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2ac60 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  r..**.** A point
2ac70 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73  er to the user s
2ac80 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2ac90 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2aca0 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61  s the fifth.** a
2acb0 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74  rgument.  ^If it
2acc0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
2acd0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
2ace0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
2acf0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2ad00 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
2ad10 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
2ad20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61  anymore)..** ^Ea
2ad30 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
2ad40 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
2ad50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2ad60 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2ad70 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
2ad80 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
2ad90 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
2ada0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2adb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
2adc0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
2add0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2ade0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2adf0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2ae00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61  .**.** ^The rema
2ae10 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
2ae20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2ae30 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
2ae40 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
2ae50 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
2ae60 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
2ae70 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
2ae80 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
2ae90 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
2aea0 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
2aeb0 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
2aec0 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
2aed0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2aee0 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
2aef0 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69  ered.  The appli
2af00 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
2af10 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
2af20 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
2af30 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
2af40 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
2af50 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
2af60 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
2af70 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
2af80 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2af90 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
2afa0 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
2afb0 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e  TRING2)..**.** ^
2afc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
2afd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2afe0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
2aff0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b000 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
2b010 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
2b020 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
2b030 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
2b040 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
2b050 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e  he collation.  ^
2b060 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2b070 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
2b080 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
2b090 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
2b0a0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2b0b0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2b0c0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
2b0d0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
2b0e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b0f0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
2b100 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  ** ^Collations a
2b110 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
2b120 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
2b130 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
2b140 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63  alls to the.** c
2b150 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2b160 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
2b170 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73  hen the [databas
2b180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2b190 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67   closed.** using
2b1a0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2b1b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2b1c0 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
2b1d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2b1e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2b1f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2b200 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
2b210 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b220 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
2b230 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2b240 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2b250 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2b260 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2b270 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2b280 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2b290 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
2b2a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2b2b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
2b2c0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2b2d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2b2e0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2b2f0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2b300 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2b310 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b320 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b330 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2b340 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2b350 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2b360 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b370 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b380 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
2b390 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
2b3a0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2b3b0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2b3c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b3d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b3e0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2b3f0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2b400 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2b410 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2b420 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2b430 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2b440 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2b450 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2b460 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2b470 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2b480 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2b490 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2b4a0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2b4b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b4c0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2b4d0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2b4e0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2b4f0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2b500 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2b510 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2b520 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2b530 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2b540 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b550 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2b560 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2b570 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2b580 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2b590 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2b5a0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2b5b0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2b5c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b5d0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2b5e0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2b5f0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2b600 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2b610 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2b620 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2b630 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2b640 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2b650 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2b660 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2b670 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2b680 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2b690 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2b6a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2b6b0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2b6c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2b6d0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2b6e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b6f0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2b700 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b710 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2b720 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2b730 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2b740 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2b750 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2b760 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b770 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2b780 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2b790 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2b7a0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2b7b0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2b7c0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2b7d0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2b7e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b7f0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2b800 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b810 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2b820 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2b830 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2b840 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2b850 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2b860 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2b870 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2b880 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2b890 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b8a0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2b8b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b8c0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2b8d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b8e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2b8f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2b900 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2b910 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2b920 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2b930 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2b940 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2b950 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2b960 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2b970 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2b980 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2b990 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2b9a0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2b9b0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2b9c0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2b9d0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2b9e0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2b9f0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2ba00 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2ba10 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2ba20 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2ba30 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2ba40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2ba50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2ba60 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2ba70 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2ba80 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2ba90 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2baa0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2bab0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2bac0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2bad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bae0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2baf0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2bb00 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2bb10 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2bb20 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2bb30 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2bb40 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2bb50 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2bb60 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2bb70 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2bb80 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2bb90 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2bba0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2bbb0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2bbc0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2bbd0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2bbe0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2bbf0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2bc00 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2bc10 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2bc20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2bc30 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2bc40 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2bc50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2bc60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2bc70 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2bc80 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2bc90 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2bca0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2bcb0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2bcc0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2bcd0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2bce0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2bcf0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2bd00 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2bd10 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2bd20 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2bd30 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2bd40 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2bd50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2bd60 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2bd70 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2bd80 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2bd90 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2bda0 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2bdb0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2bdc0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2bdd0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2bde0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2bdf0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2be00 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2be10 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2be20 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2be30 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2be40 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2be50 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2be60 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2be70 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2be80 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be90 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2bea0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2beb0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ort Time.**.** ^
2bec0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2bed0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2bee0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2bef0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2bf00 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2bf10 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2bf20 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2bf30 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2bf40 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2bf50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  .**.** ^If the o
2bf60 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2bf70 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2bf80 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2bf90 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2bfa0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2bfb0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2bfc0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2bfd0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2bfe0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2bff0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  ^The number of m
2c000 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2c010 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2c020 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2c030 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2c040 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2c050 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
2c060 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2c070 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2c080 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2c090 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2c0a0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2c0b0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2c0c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c0d0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2c0e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2c0f0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2c100 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2c110 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2c120 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2c130 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2c140 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2c150 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2c160 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2c170 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2c180 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2c190 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2c1a0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2c1b0 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2c1c0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2c1d0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2c1e0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2c1f0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2c200 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2c210 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2c220 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c230 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2c240 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2c250 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2c260 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2c270 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2c280 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2c290 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2c2a0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2c2b0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2c2c0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2c2d0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2c2e0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2c2f0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2c300 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2c310 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2c320 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2c330 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2c340 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2c350 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2c360 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2c370 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2c380 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2c390 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2c3a0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2c3b0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2c3c0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2c3d0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2c3e0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2c3f0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2c400 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2c410 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2c420 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2c430 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2c440 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c450 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2c460 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2c470 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2c480 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2c490 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2c4a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2c4b0 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2c4c0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2c4d0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c4e0 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2c4f0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2c500 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2c510 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2c520 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2c530 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2c540 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2c550 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2c560 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2c570 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2c580 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2c590 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2c5a0 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2c5b0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2c5c0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2c5d0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2c5e0 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2c5f0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2c600 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2c610 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2c620 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2c630 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2c640 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2c650 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c660 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2c670 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2c680 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
2c690 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
2c6a0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
2c6b0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
2c6c0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2c6d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2c6e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2c6f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c700 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2c710 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2c720 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2c730 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2c740 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2c750 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2c760 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2c770 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2c780 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
2c790 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2c7a0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
2c7b0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2c7c0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2c7d0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2c7e0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
2c7f0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2c800 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
2c810 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2c820 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2c830 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2c840 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2c850 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2c860 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2c870 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2c880 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
2c890 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
2c8a0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
2c8b0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
2c8c0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
2c8d0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
2c8e0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
2c8f0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
2c900 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
2c910 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
2c920 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2c930 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
2c940 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
2c950 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
2c960 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2c970 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2c980 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2c990 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2c9a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2c9b0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
2c9c0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
2c9d0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
2c9e0 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
2c9f0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2ca00 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
2ca10 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
2ca20 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
2ca30 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
2ca40 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2ca50 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2ca60 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2ca70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ca80 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2ca90 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2caa0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2cab0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
2cac0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2cad0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2cae0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2caf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2cb00 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
2cb10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cb20 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
2cb30 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
2cb40 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2cb50 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2cb60 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2cb70 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2cb80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2cb90 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2cba0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2cbb0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2cbc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2cbd0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2cbe0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2cbf0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2cc00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2cc10 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2cc20 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2cc30 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2cc40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2cc50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cc60 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
2cc70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
2cc90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ccb0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2ccc0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2ccd0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2cce0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2ccf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cd00 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
2cd10 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
2cd20 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
2cd30 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2cd40 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
2cd50 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2cd60 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
2cd70 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
2cd80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cd90 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
2cda0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2cdb0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
2cdc0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
2cdd0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
2cde0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
2cdf0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
2ce00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
2ce10 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
2ce20 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2ce30 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
2ce40 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
2ce50 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
2ce60 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
2ce70 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
2ce80 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
2ce90 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
2cea0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2ceb0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2cec0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2ced0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2cee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cef0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2cf00 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2cf10 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2cf20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cf30 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
2cf40 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2cf50 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2cf60 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2cf70 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2cf80 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2cf90 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
2cfa0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
2cfb0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2cfc0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2cfd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2cfe0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2cff0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d010 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2d020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
2d030 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2d040 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2d050 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2d060 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2d070 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2d080 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2d090 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2d0a0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
2d0b0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2d0c0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2d0d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
2d0e0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
2d0f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d110 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d120 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
2d130 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2d140 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2d150 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
2d160 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2d170 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2d180 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2d190 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2d1a0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2d1b0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2d1c0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2d1d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
2d1e0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
2d1f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
2d200 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
2d210 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
2d220 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
2d230 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2d240 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
2d250 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2d260 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2d270 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d280 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2d290 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2d2a0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
2d2b0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
2d2c0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2d2d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d2e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2d2f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2d300 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2d310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d320 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2d330 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
2d340 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2d350 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2d360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2d370 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2d380 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2d390 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2d3a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2d3b0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2d3c0 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
2d3d0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
2d3e0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
2d3f0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
2d400 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2d410 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d420 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2d430 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2d440 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2d450 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2d460 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2d470 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2d480 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2d490 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
2d4a0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2d4b0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2d4c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
2d4d0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2d4e0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2d4f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2d500 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2d510 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2d520 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2d530 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
2d540 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
2d550 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
2d560 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
2d570 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
2d580 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
2d590 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
2d5a0 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
2d5b0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2d5c0 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
2d5d0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
2d5e0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
2d5f0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
2d600 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
2d610 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
2d620 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
2d630 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
2d640 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2d650 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2d660 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2d670 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2d680 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2d690 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2d6a0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2d6b0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2d6c0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2d6d0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2d6e0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2d6f0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
2d700 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2d710 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2d720 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2d730 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
2d740 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2d750 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
2d760 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d770 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
2d780 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2d790 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2d7a0 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2d7b0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2d7c0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2d7d0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2d7e0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2d7f0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2d800 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2d810 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2d820 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2d830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d840 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2d850 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2d860 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2d870 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2d880 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2d890 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2d8a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2d8b0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2d8c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2d8d0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2d8e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2d8f0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2d900 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2d910 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2d920 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2d930 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2d940 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2d950 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2d960 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2d970 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d990 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2d9a0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2d9b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2d9c0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2d9d0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2d9e0 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2d9f0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2da00 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2da10 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2da20 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2da30 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2da40 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2da50 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2da60 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2da70 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2da80 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2da90 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2daa0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2dab0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2dac0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2dad0 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2dae0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2daf0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2db00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2db10 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2db20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2db30 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2db40 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2db50 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2db60 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2db70 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2db80 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2db90 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2dba0 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2dbb0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2dbc0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2dbd0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2dbe0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2dbf0 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2dc00 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2dc10 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2dc20 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2dc30 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2dc40 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2dc50 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2dc60 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2dc70 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2dc80 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2dc90 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2dca0 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2dcb0 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2dcc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2dcd0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2dce0 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2dcf0 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2dd00 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2dd10 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2dd20 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2dd30 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2dd40 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2dd50 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2dd60 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2dd70 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2dd80 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2dd90 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2dda0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2ddb0 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2ddc0 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2ddd0 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2dde0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2ddf0 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2de00 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2de10 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2de20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2de30 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2de40 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2de50 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2de60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2de70 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2de80 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2de90 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2dea0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2deb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2dec0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2ded0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2dee0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2def0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2df00 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2df10 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2df20 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2df30 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2df40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2df50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2df60 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2df70 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2df80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2df90 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2dfa0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2dfb0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2dfc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dfd0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2dfe0 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2dff0 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2e000 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2e010 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2e020 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2e030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e040 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2e050 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2e060 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2e070 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2e080 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2e090 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e0a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2e0b0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2e0c0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2e0d0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2e0e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2e0f0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2e100 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2e110 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2e120 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2e130 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2e140 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2e150 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2e160 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2e170 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2e180 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2e190 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2e1a0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2e1b0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2e1c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2e1d0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2e1e0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2e1f0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2e200 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2e210 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2e220 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2e230 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2e240 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2e250 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2e260 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2e270 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2e280 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2e290 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2e2a0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2e2b0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2e2c0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2e2d0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2e2e0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2e2f0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2e300 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2e310 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2e320 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2e330 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2e340 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2e350 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2e360 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2e370 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2e380 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2e390 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2e3a0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2e3b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2e3c0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2e3d0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2e3e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2e3f0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2e400 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e410 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2e420 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2e430 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2e440 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2e450 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2e460 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2e470 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2e480 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2e490 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2e4a0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2e4b0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2e4c0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2e4d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2e4e0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2e4f0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2e500 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2e510 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2e520 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2e530 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2e540 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2e550 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2e560 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2e570 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2e580 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2e590 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2e5a0 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2e5b0 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2e5c0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2e5d0 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2e5e0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2e5f0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2e600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2e610 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2e620 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2e630 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2e640 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2e650 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2e660 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2e670 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2e680 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2e690 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2e6a0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2e6b0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2e6c0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2e6d0 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2e6e0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2e6f0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2e700 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2e710 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2e720 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2e730 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2e740 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2e750 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2e760 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e770 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2e780 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2e790 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2e7a0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2e7b0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2e7c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2e7d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2e7e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e7f0 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2e800 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2e810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e820 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2e830 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2e840 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2e850 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2e860 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2e870 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2e880 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2e890 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2e8a0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2e8b0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2e8c0 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2e8d0 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2e8e0 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2e8f0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e900 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2e910 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2e920 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2e930 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2e940 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2e950 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2e960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2e970 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2e980 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2e990 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e9a0 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2e9b0 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2e9c0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2e9d0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2e9e0 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2e9f0 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2ea00 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2ea10 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2ea20 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2ea30 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2ea40 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2ea50 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2ea60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2ea70 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2ea80 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2ea90 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2eaa0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2eab0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2eac0 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2ead0 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2eae0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2eaf0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2eb00 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2eb10 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2eb20 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2eb30 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2eb40 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2eb50 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2eb60 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2eb70 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2eb80 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2eb90 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2eba0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2ebb0 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2ebc0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2ebd0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2ebe0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2ebf0 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2ec00 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2ec10 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2ec20 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2ec30 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2ec40 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2ec50 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2ec60 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2ec70 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2ec80 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2ec90 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2eca0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2ecb0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2ecc0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2ecd0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2ece0 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2ecf0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2ed00 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2ed10 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2ed20 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2ed30 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2ed40 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2ed50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2ed60 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2ed70 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2ed80 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2ed90 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2eda0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2edb0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2edc0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2edd0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2ede0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2edf0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ee00 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2ee10 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2ee20 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2ee30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2ee40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2ee50 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2ee60 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2ee70 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2ee80 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2ee90 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2eea0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2eeb0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2eec0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2eed0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2eee0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2eef0 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
2ef00 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2ef10 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2ef20 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2ef30 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2ef40 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
2ef50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2ef60 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2ef70 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2ef80 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2ef90 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
2efa0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2efb0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2efc0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2efd0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2efe0 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2eff0 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
2f000 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
2f010 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
2f020 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
2f030 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
2f040 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
2f050 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
2f060 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
2f070 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
2f080 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
2f090 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2f0a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f0b0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2f0c0 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
2f0d0 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
2f0e0 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
2f0f0 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
2f100 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
2f110 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
2f120 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
2f130 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
2f140 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2f150 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2f160 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2f170 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2f180 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2f190 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2f1a0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2f1b0 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
2f1c0 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2f1d0 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2f1e0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2f1f0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2f200 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2f210 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2f220 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
2f230 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2f240 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2f250 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2f260 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2f270 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2f280 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2f290 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2f2a0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2f2b0 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2f2c0 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2f2d0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2f2e0 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2f2f0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2f300 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2f310 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2f320 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2f330 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2f340 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2f350 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2f360 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f370 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f380 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2f390 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2f3a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2f3b0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f3c0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f3d0 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2f3e0 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2f3f0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2f400 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
2f410 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2f420 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2f430 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2f440 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2f450 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2f460 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2f470 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2f480 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2f490 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2f4a0 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2f4b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f4c0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2f4d0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2f4e0 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2f4f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2f500 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2f510 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2f520 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2f530 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2f540 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2f550 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2f560 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2f570 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2f580 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2f590 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2f5a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2f5b0 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2f5c0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2f5d0 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
2f5e0 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
2f5f0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
2f600 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2f610 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
2f620 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2f630 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2f640 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
2f650 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2f660 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2f670 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2f680 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2f690 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2f6a0 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2f6b0 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2f6c0 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2f6d0 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2f6e0 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
2f6f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
2f700 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
2f710 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
2f720 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
2f730 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
2f740 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
2f750 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
2f760 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
2f770 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
2f780 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
2f790 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
2f7a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
2f7b0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
2f7c0 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
2f7d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f7e0 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
2f7f0 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
2f800 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2f810 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
2f820 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2f830 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f840 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f850 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f860 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f870 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f880 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f890 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
2f8a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
2f8b0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
2f8c0 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
2f8d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2f8e0 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
2f8f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2f900 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2f910 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f920 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
2f930 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2f940 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
2f950 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
2f960 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2f970 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
2f980 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
2f990 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2f9a0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
2f9b0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
2f9c0 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
2f9d0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2f9e0 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
2f9f0 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
2fa00 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
2fa10 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
2fa20 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
2fa30 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2fa40 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
2fa50 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
2fa60 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
2fa70 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
2fa80 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2fa90 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
2faa0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
2fab0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
2fac0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2fad0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2fae0 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
2faf0 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
2fb00 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
2fb10 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
2fb20 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2fb30 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2fb40 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2fb50 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2fb60 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2fb70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2fb80 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2fb90 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2fba0 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2fbb0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2fbc0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2fbd0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
2fbe0 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
2fbf0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2fc00 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
2fc10 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2fc20 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2fc30 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2fc40 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
2fc50 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
2fc60 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
2fc70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2fc80 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2fc90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fca0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
2fcb0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
2fcc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2fcd0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
2fce0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
2fcf0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
2fd00 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
2fd10 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
2fd20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2fd30 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2fd40 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2fd50 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
2fd60 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2fd70 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2fd80 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2fd90 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
2fda0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2fdb0 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
2fdc0 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
2fdd0 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
2fde0 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
2fdf0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
2fe00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
2fe10 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2fe20 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2fe30 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
2fe40 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2fe50 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
2fe60 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
2fe70 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
2fe80 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
2fe90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2fea0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
2feb0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2fec0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
2fed0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
2fee0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
2fef0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2ff00 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
2ff10 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
2ff20 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
2ff30 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
2ff40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2ff50 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
2ff60 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
2ff70 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
2ff80 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
2ff90 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
2ffa0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
2ffb0 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
2ffc0 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
2ffd0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
2ffe0 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
2fff0 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
30000 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
30010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30020 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
30030 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
30040 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
30050 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
30060 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
30070 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
30080 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
30090 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
300a0 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
300b0 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
300c0 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
300d0 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
300e0 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
300f0 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
30100 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
30110 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
30120 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
30130 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
30140 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
30150 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
30160 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
30170 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
30180 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
30190 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
301a0 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
301b0 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
301c0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
301d0 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
301e0 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
301f0 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
30200 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
30210 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
30220 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
30230 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
30240 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
30250 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
30260 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
30270 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
30280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30290 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
302a0 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
302b0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
302c0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
302d0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
302e0 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
302f0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
30300 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
30310 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
30320 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
30330 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
30340 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
30350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30360 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
30370 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
30380 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30390 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
303a0 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
303b0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
303c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
303d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
303e0 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
303f0 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
30400 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
30410 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30420 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
30430 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
30440 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
30450 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
30460 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
30470 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
30480 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
30490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
304a0 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
304b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
304c0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
304d0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
304e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
304f0 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
30500 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
30510 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
30520 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
30530 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
30540 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
30550 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
30560 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
30570 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
30580 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
30590 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
305a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
305b0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
305c0 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
305d0 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
305e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
305f0 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
30600 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
30610 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
30620 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
30630 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
30640 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
30650 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
30660 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
30670 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
30680 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
30690 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
306a0 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
306b0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
306c0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
306d0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
306e0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
306f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
30700 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30710 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  (void);../*.** T
30720 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
30730 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30740 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
30750 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
30760 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
30770 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
30780 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
30790 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
307a0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
307b0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
307c0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
307d0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
307e0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
307f0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
30800 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30810 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
30820 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
30830 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
30840 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
30850 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
30860 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
30870 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
30880 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
30890 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
308a0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
308b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
308c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
308d0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
308e0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
308f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
30900 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
30910 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
30920 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
30930 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
30940 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
30950 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
30960 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
30970 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
30980 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
30990 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
309a0 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  le Object.** KEY
309b0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
309c0 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
309d0 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a  able module}.**.
309e0 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
309f0 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
30a00 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
30a10 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
30a20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
30a30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30a40 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
30a50 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
30a60 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
30a70 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
30a80 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
30a90 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69  ule..**.** ^A vi
30aa0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30ab0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
30ac0 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
30ad0 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
30ae0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
30af0 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
30b00 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
30b10 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
30b20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
30b30 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
30b40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30b50 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
30b60 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74  * ^The registrat
30b70 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
30b80 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
30b90 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
30ba0 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
30bb0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
30bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30bd0 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
30be0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
30bf0 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
30c00 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
30c10 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
30c20 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
30c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30c40 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
30c50 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
30c60 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
30c70 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
30c80 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
30c90 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
30ca0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
30cb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
30cc0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
30cd0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
30ce0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
30cf0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
30d00 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
30d10 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
30d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
30d30 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
30d40 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
30d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
30d60 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
30d70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
30d80 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
30d90 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
30da0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
30db0 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
30dc0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
30dd0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
30de0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
30df0 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
30e00 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
30e10 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
30e20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30e30 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
30e40 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
30e50 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
30e60 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
30e70 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
30e80 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
30e90 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30ea0 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
30eb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
30ec0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
30ed0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
30ee0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
30ef0 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
30f00 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
30f10 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
30f20 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
30f30 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
30f40 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
30f50 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30f60 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
30f70 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
30f80 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
30f90 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30fa0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
30fb0 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
30fc0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
30fd0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
30fe0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
30ff0 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
31000 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
31010 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
31020 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
31030 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
31040 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
31050 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
31060 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
31070 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
31080 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
31090 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
310a0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
310b0 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
310c0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
310d0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
310e0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
310f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31100 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
31110 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31120 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31130 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
31140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31150 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
31160 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
31170 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31180 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
31190 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
311a0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
311b0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
311c0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
311d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
311e0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
311f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31200 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
31210 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
31220 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
31230 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
31240 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
31250 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
31260 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
31270 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
31280 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
31290 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
312a0 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
312b0 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
312c0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
312d0 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
312e0 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
312f0 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
31300 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
31310 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
31320 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
31330 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
31340 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
31350 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
31360 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
31370 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
31380 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75  .**.** <pre>colu
31390 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e  mn OP expr</pre>
313a0 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
313b0 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
313c0 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
313d0 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74  =.)^  ^(The part
313e0 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20  icular operator 
313f0 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20  is.** stored in 
31400 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
31410 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78  .)^  ^(The index
31420 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
31430 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
31440 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
31450 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
31460 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
31470 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
31480 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
31490 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
314a0 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
314b0 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
314c0 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
314d0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
314e0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
314f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
31500 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
31510 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
31520 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
31530 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
31540 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
31550 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
31560 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
31570 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
31580 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
31590 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
315a0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
315b0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
315c0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
315d0 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
315e0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
315f0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
31600 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
31610 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
31620 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
31630 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
31640 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
31650 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
31660 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
31670 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
31680 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
31690 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
316a0 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
316b0 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
316c0 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
316d0 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
316e0 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
316f0 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
31700 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
31710 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
31720 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
31730 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
31740 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
31750 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
31760 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
31770 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
31780 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
31790 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
317a0 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
317b0 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
317c0 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
317d0 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
317e0 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
317f0 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
31800 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
31810 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
31820 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
31830 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
31840 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
31850 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
31860 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
31870 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
31880 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
31890 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
318a0 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
318b0 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
318c0 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
318d0 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
318e0 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
318f0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
31900 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
31910 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
31920 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
31930 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
31940 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
31950 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
31960 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
31970 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
31980 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
31990 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
319a0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
319b0 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
319c0 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
319d0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
319e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
319f0 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
31a00 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
31a10 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
31a20 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
31a30 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
31a40 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
31a50 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
31a60 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
31a70 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
31a80 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
31a90 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
31aa0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
31ab0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
31ac0 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
31ad0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
31ae0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31af0 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
31b00 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
31b10 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
31b20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
31b30 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
31b40 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
31b50 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
31b60 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
31b70 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
31b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31b90 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
31ba0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
31bb0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
31bc0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
31bd0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
31be0 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
31bf0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
31c00 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
31c10 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
31c20 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
31c30 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
31c40 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
31c50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
31c60 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
31c70 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
31c80 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
31c90 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
31ca0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
31cb0 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
31cc0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
31cd0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
31ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31cf0 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
31d00 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
31d10 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
31d20 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31d30 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
31d40 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
31d50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
31d60 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
31d70 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
31d80 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
31d90 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
31da0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
31db0 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
31dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31dd0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
31de0 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
31df0 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
31e00 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
31e10 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
31e20 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
31e30 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
31e40 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
31e50 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
31e60 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
31e70 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
31e80 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
31e90 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
31ea0 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
31eb0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
31ec0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
31ed0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
31ee0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
31ef0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
31f00 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
31f10 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
31f20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
31f30 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
31f40 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
31f50 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
31f60 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
31f70 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
31f80 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
31f90 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
31fa0 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
31fb0 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
31fc0 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
31fd0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
31fe0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
31ff0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
32000 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
32010 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
32020 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
32030 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
32040 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
32050 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32060 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
32070 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32080 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
32090 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
320a0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
320b0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
320c0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
320d0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
320e0 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
320f0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
32100 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
32110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32120 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
32130 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
32140 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
32150 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
32160 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   Implementation.
32170 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
32180 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
32190 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
321a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
321b0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
321c0 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d   ^Module names m
321d0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
321e0 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
321f0 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
32200 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
32210 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
32220 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
32230 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
32240 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
32250 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
32260 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20  .** ^The module 
32270 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72  name is register
32280 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ed on the [datab
32290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
322a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
322b0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
322c0 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20  ter.  ^The name 
322d0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73  of the module is
322e0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a   given by the .*
322f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
32300 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  er.  ^The third 
32310 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
32320 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
32330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32340 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
32350 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
32360 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20   ^The fourth.** 
32370 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
32380 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74  arbitrary client
32390 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
323a0 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
323b0 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  ough.** into the
323c0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
323d0 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
323e0 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
323f0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a   table module.**
32400 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74   when a new virt
32410 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20  ual table is be 
32420 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72  being created or
32430 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a   reinitialized..
32440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32450 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32460 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
32470 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61  has a fifth para
32480 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
32490 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
324a0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
324b0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e  the pClientData.
324c0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a    ^SQLite will.*
324d0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  * invoke the des
324e0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
324f0 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   (if it is not N
32500 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65  ULL) when SQLite
32510 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  .** no longer ne
32520 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44  eds the pClientD
32530 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ata pointer.  ^T
32540 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
32550 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
32560 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
32570 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
32580 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
32590 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
325a0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
325b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
325c0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
325d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
325e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
325f0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
32600 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
32610 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
32620 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
32630 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
32640 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
32650 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
32660 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
32670 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
32680 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
32690 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
326a0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
326b0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
326c0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
326d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
326e0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
326f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32700 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
32710 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
32720 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
32730 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
32740 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
32750 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
32760 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
32770 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
32780 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
32790 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
327a0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
327b0 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
327c0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
327d0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
327e0 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
327f0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
32800 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
32810 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
32820 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
32830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32840 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
32850 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
32860 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
32870 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
32880 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
32890 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
328a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
328b0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
328c0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
328d0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
328e0 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
328f0 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
32900 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
32910 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
32920 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
32930 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
32940 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
32950 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32960 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
32970 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
32980 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
32990 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
329a0 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
329b0 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
329c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
329d0 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
329e0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
329f0 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
32a00 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
32a10 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
32a20 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
32a30 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
32a40 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
32a50 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
32a60 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
32a70 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
32a80 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
32a90 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
32aa0 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
32ab0 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
32ac0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
32ad0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
32ae0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
32af0 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
32b00 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
32b10 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
32b20 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
32b30 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
32b40 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
32b50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
32b60 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
32b70 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
32b80 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
32b90 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
32ba0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
32bb0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
32bc0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
32bd0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
32be0 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
32bf0 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
32c00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
32c10 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
32c20 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
32c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32c40 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
32c50 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
32c60 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
32c70 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
32c80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32c90 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
32ca0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
32cb0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
32cc0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
32cd0 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
32ce0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
32cf0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
32d00 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
32d10 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
32d20 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
32d30 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
32d40 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
32d50 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
32d60 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
32d70 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
32d80 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
32d90 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
32da0 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
32db0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
32dc0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
32dd0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
32de0 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
32df0 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
32e00 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
32e10 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
32e20 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
32e30 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
32e40 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
32e50 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
32e60 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
32e70 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
32e80 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
32e90 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
32ea0 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
32eb0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
32ec0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
32ed0 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
32ee0 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
32ef0 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
32f00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
32f10 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
32f20 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
32f30 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
32f40 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
32f50 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
32f60 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
32f70 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
32f80 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
32f90 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
32fa0 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
32fb0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
32fc0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
32fd0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
32fe0 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
32ff0 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
33000 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
33010 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
33020 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
33030 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
33040 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
33050 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
33060 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
33070 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
33080 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
33090 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
330a0 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
330b0 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
330c0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
330d0 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
330e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
330f0 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
33100 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
33110 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
33120 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
33130 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
33140 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
33150 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
33160 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
33170 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
33180 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
33190 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
331a0 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
331b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
331c0 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
331d0 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
331e0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
331f0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
33200 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
33210 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
33220 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
33230 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
33240 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
33250 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
33260 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33270 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
33280 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
33290 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
332a0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
332b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
332c0 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
332d0 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
332e0 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
332f0 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
33300 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
33310 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
33320 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
33330 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
33340 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
33350 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
33360 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
33370 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
33380 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
33390 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
333a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
333b0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
333c0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
333d0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
333e0 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
333f0 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
33400 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
33410 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
33420 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
33430 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
33440 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
33450 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
33460 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
33470 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
33480 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
33490 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
334a0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
334b0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
334c0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
334d0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
334e0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
334f0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
33500 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
33510 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
33520 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
33530 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
33540 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
33550 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
33560 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
33570 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
33580 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
33590 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
335a0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
335b0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
335c0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
335d0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
335e0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
335f0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
33600 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
33610 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33620 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
33630 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
33640 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
33650 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
33660 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
33670 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
33680 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
33690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
336a0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
336b0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
336c0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
336d0 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
336e0 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
336f0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
33700 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
33710 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
33720 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
33730 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
33740 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
33750 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
33760 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
33770 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
33780 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
33790 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
337a0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
337b0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
337c0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
337d0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
337e0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
337f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
33800 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
33810 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
33820 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
33830 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
33840 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
33850 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
33860 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
33870 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
33880 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
33890 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
338a0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
338b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
338c0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
338d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
338e0 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
338f0 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
33900 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
33910 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
33920 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
33930 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
33940 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
33950 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
33960 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
33970 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
33980 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
33990 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
339a0 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
339b0 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
339c0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
339d0 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
339e0 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
339f0 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
33a00 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
33a10 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
33a20 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
33a30 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
33a40 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
33a50 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
33a60 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
33a70 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
33a80 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
33a90 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
33aa0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
33ab0 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
33ac0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
33ad0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
33ae0 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
33af0 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
33b00 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
33b10 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
33b20 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
33b30 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
33b40 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
33b50 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
33b60 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
33b70 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
33b80 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
33b90 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
33ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
33bb0 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
33bc0 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
33bd0 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
33be0 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
33bf0 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
33c00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
33c10 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
33c20 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
33c30 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
33c40 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
33c50 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
33c60 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
33c70 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
33c80 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
33c90 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
33ca0 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
33cb0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
33cc0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
33cd0 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
33ce0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
33cf0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
33d00 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
33d10 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
33d20 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
33d30 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
33d40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
33d50 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
33d60 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
33d70 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
33d80 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
33d90 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
33da0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
33db0 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
33dc0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
33dd0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
33de0 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
33df0 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
33e00 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
33e10 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
33e20 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
33e30 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
33e40 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
33e50 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
33e60 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
33e70 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
33e80 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
33e90 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
33ea0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
33eb0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
33ec0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
33ed0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
33ee0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
33ef0 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
33f00 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
33f10 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
33f20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
33f30 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
33f40 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
33f50 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
33f60 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
33f70 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
33f80 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
33f90 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
33fa0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
33fb0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
33fc0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
33fd0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
33fe0 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
33ff0 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
34000 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
34010 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
34020 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
34030 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
34040 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
34050 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
34060 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
34070 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
34080 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
34090 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
340a0 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
340b0 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
340c0 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
340d0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
340e0 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
340f0 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
34100 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
34110 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
34120 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
34130 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
34140 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
34150 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
34160 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
34170 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
34180 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
34190 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
341a0 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
341b0 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
341c0 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
341d0 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
341e0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
341f0 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
34200 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
34210 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
34220 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
34230 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
34240 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
34250 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
34260 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
34270 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
34280 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
34290 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
342a0 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
342b0 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
342c0 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
342d0 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
342e0 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
342f0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
34300 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
34310 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
34320 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
34330 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
34340 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
34350 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
34360 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
34370 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
34380 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
34390 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
343a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
343b0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
343c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
343d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
343e0 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
343f0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
34400 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
34410 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
34420 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
34430 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
34440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34450 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
34460 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73  le.**.** ^Closes
34470 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
34480 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  andle]..**.** ^C
34490 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
344a0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
344b0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
344c0 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
344d0 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
344e0 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
344f0 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
34500 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
34510 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34520 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
34530 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
34540 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77  e]..** ^If any w
34550 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20  rites were made 
34560 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65  to the BLOB, the
34570 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20  y might be held 
34580 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69  in cache.** unti
34590 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72  l the close oper
345a0 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69  ation if they wi
345b0 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ll fit..**.** ^(
345c0 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
345d0 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
345e0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
345f0 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
34600 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
34610 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
34620 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
34630 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
34640 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
34650 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
34660 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
34670 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
34680 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
34690 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
346a0 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a  rn value.)^.**.*
346b0 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20  * ^(The BLOB is 
346c0 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
346d0 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
346e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
346f0 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
34700 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
34710 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
34720 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  .)^.**.** ^Calli
34730 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
34740 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  with a null poin
34750 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f 75  ter (such as wou
34760 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a  ld be returned.*
34770 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63 61  * by a failed ca
34780 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
34790 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20  lob_open()]) is 
347a0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
347b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
347c0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
347d0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
347e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
347f0 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
34800 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
34810 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65  .** ^Returns the
34820 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
34830 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73  f the BLOB acces
34840 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a  sible via the .*
34850 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  * successfully o
34860 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pened [BLOB hand
34870 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
34880 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a  argument.  ^The.
34890 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62  ** incremental b
348a0 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73  lob I/O routines
348b0 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f   can only read o
348c0 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78  r overwriting ex
348d0 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63  isting.** blob c
348e0 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e  ontent; they can
348f0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73  not change the s
34900 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a  ize of a blob..*
34910 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34920 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
34930 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
34940 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
34950 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
34960 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
34970 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34980 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
34990 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
349a0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
349b0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
349c0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
349d0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
349e0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
349f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
34a00 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34a10 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
34a20 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
34a30 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
34a40 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
34a50 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
34a60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34a70 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
34a80 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
34a90 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ly.**.** ^(This 
34aa0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
34ab0 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
34ac0 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  om an open [BLOB
34ad0 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a   handle] into a.
34ae0 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
34af0 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74  ed buffer. N byt
34b00 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
34b10 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65  opied into buffe
34b20 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  r Z.** from the 
34b30 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
34b40 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
34b50 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ffset.)^.**.** ^
34b60 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
34b70 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
34b80 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
34b90 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
34ba0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
34bb0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
34bc0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
34bd0 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f  ad.  ^If N or iO
34be0 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
34bf0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
34c00 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
34c10 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
34c20 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e  ta is read..** ^
34c30 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
34c40 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
34c50 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
34c60 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
34c70 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
34c80 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
34c90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
34ca0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
34cb0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
34cc0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
34cd0 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
34ce0 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
34cf0 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
34d00 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
34d10 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ABORT]..**.** ^(
34d20 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
34d30 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20  te3_blob_read() 
34d40 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
34d50 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
34d60 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
34d70 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34d80 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34d90 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
34da0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
34db0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34dc0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
34dd0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
34de0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
34df0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34e00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34e10 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34e20 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34e30 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34e40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34e50 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
34e60 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
34e70 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
34e80 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34e90 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34ea0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
34eb0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34ec0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
34ed0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
34ee0 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ite()]..*/.int s
34ef0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
34f00 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
34f10 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
34f20 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
34f30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34f40 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
34f50 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
34f60 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ally.**.** ^This
34f70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
34f80 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
34f90 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  into an open [BL
34fa0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20  OB handle] from 
34fb0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
34fc0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20  lied buffer. ^N 
34fd0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34fe0 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
34ff0 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
35000 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
35010 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
35020 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
35030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f  .** ^If the [BLO
35040 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
35050 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
35060 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
35070 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
35080 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
35090 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
350a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
350b0 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
350c0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
350d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
350e0 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
350f0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  ^This function m
35100 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
35110 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
35120 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
35130 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
35140 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
35150 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
35160 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
35170 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
35180 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
35190 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
351a0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
351b0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
351c0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
351d0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
351e0 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20  written.  ^If N 
351f0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
35200 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
35210 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
35220 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
35230 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ritten..** The s
35240 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
35250 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d  (and hence the m
35260 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
35270 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61  N+iOffset).** ca
35280 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
35290 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
352a0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
352b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
352c0 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f  * ^An attempt to
352d0 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70   write to an exp
352e0 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
352f0 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
35300 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
35310 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
35320 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68  .  ^Writes to th
35330 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
35340 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
35350 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
35360 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
35370 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
35380 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
35390 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
353a0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
353b0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
353c0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
353d0 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
353e0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
353f0 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
35400 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
35410 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
35420 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
35430 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  ts..**.** ^(On s
35440 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f  uccess, sqlite3_
35450 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74  blob_write() ret
35460 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
35470 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
35480 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f    [error code] o
35490 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
354a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
354b0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
354c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
354d0 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
354e0 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
354f0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
35500 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
35510 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
35520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
35530 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
35540 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
35550 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
35560 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
35570 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
35580 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
35590 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
355a0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
355b0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
355c0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
355d0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
355e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
355f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
35600 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
35610 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
35620 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
35630 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
35640 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
35650 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35660 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65  EF: Virtual File
35670 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
35680 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
35690 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
356a0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
356b0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
356c0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
356d0 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
356e0 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
356f0 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
35700 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74  tem.  Most SQLit
35710 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  e builds come wi
35720 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
35730 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
35740 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
35750 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
35760 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
35770 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
35780 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
35790 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
357a0 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
357b0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
357c0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
357d0 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  vided..**.** ^Th
357e0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
357f0 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
35800 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35810 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20   to a VFS given 
35820 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61  its name..** ^Na
35830 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
35840 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  sitive..** ^Name
35850 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
35860 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
35870 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72  ngs..** ^If ther
35880 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
35890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
358a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
358b0 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
358c0 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
358d0 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
358e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20  ned..**.** ^New 
358f0 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
35900 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
35910 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
35920 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56  ..** ^Each new V
35930 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64  FS becomes the d
35940 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68  efault VFS if th
35950 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
35960 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  is set..** ^The 
35970 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
35980 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
35990 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
359a0 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f  t injury..** ^To
359b0 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
359c0 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
359d0 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
359e0 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
359f0 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
35a00 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
35a10 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
35a20 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
35a30 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
35a40 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
35a50 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
35a60 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
35a70 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
35a80 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
35a90 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
35aa0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
35ab0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35ac0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
35ad0 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74  .**.** ^Unregist
35ae0 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
35af0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
35b00 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
35b10 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68  face..** ^(If th
35b20 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
35b30 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
35b40 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
35b50 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
35b60 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
35b70 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
35b80 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
35b90 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  .)^.*/.sqlite3_v
35ba0 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f  fs *sqlite3_vfs_
35bb0 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20  find(const char 
35bc0 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20  *zVfsName);.int 
35bd0 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
35be0 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
35bf0 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29  *, int makeDflt)
35c00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
35c10 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c  s_unregister(sql
35c20 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a  ite3_vfs*);../*.
35c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
35c40 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  exes.**.** The S
35c50 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
35c60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  these routines f
35c70 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e  or thread.** syn
35c80 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68  chronization. Th
35c90 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
35ca0 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
35cb0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
35cc0 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
35cd0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
35ce0 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
35cf0 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
35d00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
35d10 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
35d20 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
35d30 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
35d40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35d50 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75  s.** of these mu
35d60 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
35d70 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
35d80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
35d90 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
35da0 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
35db0 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68  pile-time.  ^(Th
35dc0 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69  e following.** i
35dd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61  mplementations a
35de0 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  re available in 
35df0 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a  the SQLite core:
35e00 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
35e10 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
35e20 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_OS2.** <li>  
35e30 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
35e40 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20  HREAD.** <li>   
35e50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
35e60 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
35e70 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
35e80 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  </ul>)^.**.** ^T
35e90 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
35ea0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
35eb0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
35ec0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
35ed0 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
35ee0 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
35ef0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
35f00 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
35f10 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
35f20 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49  tion.  ^The SQLI
35f30 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
35f40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
35f50 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
35f60 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
35f70 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
35f80 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
35f90 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
35fa0 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
35fb0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  s..**.** ^(If SQ
35fc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
35fd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
35fe0 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72  _MUTEX_APPDEF pr
35ff0 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61  eprocessor.** ma
36000 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74  cro defined (wit
36010 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45  h "-DSQLITE_MUTE
36020 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68  X_APPDEF=1"), th
36030 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69  en no mutex.** i
36040 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
36050 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74   included with t
36060 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74  he library. In t
36070 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  his case the.** 
36080 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
36090 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d   supply a custom
360a0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
360b0 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a  ation using the.
360c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
360d0 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20  G_MUTEX] option 
360e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
360f0 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e  onfig() function
36100 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  .** before calli
36110 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ng sqlite3_initi
36120 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f  alize() or any o
36130 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69  ther public sqli
36140 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  te3_.** function
36150 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69   that calls sqli
36160 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
36170 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
36180 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
36190 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c  oc() routine all
361a0 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20  ocates a new.** 
361b0 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e  mutex and return
361c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
361d0 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e  t. ^If it return
361e0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
361f0 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
36200 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
36210 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69  llocated.  ^SQLi
36220 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
36230 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
36240 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
36250 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
36260 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  .** to sqlite3_m
36270 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20  utex_alloc() is 
36280 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
36290 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a  eger constants:.
362a0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
362b0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
362c0 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _FAST.** <li>  S
362d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
362e0 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  RSIVE.** <li>  S
362f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
36300 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69  IC_MASTER.** <li
36310 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36320 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c  STATIC_MEM.** <l
36330 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36340 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20  _STATIC_MEM2.** 
36350 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36360 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a  EX_STATIC_PRNG.*
36370 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
36380 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a  UTEX_STATIC_LRU.
36390 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
363a0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
363b0 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  2.** </ul>)^.**.
363c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 77  ** ^The first tw
363d0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c  o constants (SQL
363e0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
363f0 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36400 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61  RECURSIVE).** ca
36410 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
36420 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
36430 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
36440 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75  ex.  ^The new mu
36450 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
36460 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
36470 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
36480 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
36490 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
364a0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
364b0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a  _FAST is used..*
364c0 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
364d0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
364e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
364f0 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
36500 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
36510 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36520 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
36530 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
36540 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
36550 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
36560 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72  only request a r
36570 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69  ecursive mutex i
36580 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65  n.** cases where
36590 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73   it really needs
365a0 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73   one.  ^If a fas
365b0 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76  ter non-recursiv
365c0 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  e mutex.** imple
365d0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61  mentation is ava
365e0 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f  ilable on the ho
365f0 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65  st platform, the
36600 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d   mutex subsystem
36610 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e  .** might return
36620 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e   such a mutex in
36630 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c   response to SQL
36640 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a  ITE_MUTEX_FAST..
36650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72  **.** ^The other
36660 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74   allowed paramet
36670 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ers to sqlite3_m
36680 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e  utex_alloc() (an
36690 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20  ything other.** 
366a0 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  than SQLITE_MUTE
366b0 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
366c0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
366d0 45 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a  E) each return.*
366e0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
366f0 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74   static preexist
36700 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78  ing mutex.  ^Six
36710 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
36720 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74  are.** used by t
36730 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  he current versi
36740 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46  on of SQLite.  F
36750 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
36760 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20  f SQLite.** may 
36770 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  add additional s
36780 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20  tatic mutexes.  
36790 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  Static mutexes a
367a0 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  re for internal.
367b0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
367c0 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
367d0 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51  ions that use SQ
367e0 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f  Lite mutexes sho
367f0 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20  uld.** use only 
36800 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
36810 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  xes returned by 
36820 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
36830 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  T or.** SQLITE_M
36840 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a  UTEX_RECURSIVE..
36850 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
36860 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
36870 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
36880 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
36890 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
368a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
368b0 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
368c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
368d0 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
368e0 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
368f0 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
36900 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f  y call.  ^But fo
36910 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20  r the static.** 
36920 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
36930 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
36940 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
36950 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
36960 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
36970 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
36980 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
36990 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
369a0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
369b0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
369c0 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
369d0 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73  tex.  ^SQLite is
369e0 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c   careful to deal
369f0 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20  locate every.** 
36a00 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68  dynamic mutex th
36a10 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e  at it allocates.
36a20 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75    The dynamic mu
36a30 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62  texes must not b
36a40 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e  e in.** use when
36a50 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
36a60 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69  cated.  Attempti
36a70 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ng to deallocate
36a80 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74   a static.** mut
36a90 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ex results in un
36aa0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
36ab0 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72  .  ^SQLite never
36ac0 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
36ad0 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  a static mutex..
36ae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36af0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36b00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
36b10 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
36b20 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
36b30 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
36b40 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65  ^If another thre
36b50 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
36b60 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
36b70 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
36b80 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
36b90 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
36ba0 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
36bb0 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
36bc0 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71  E_BUSY.  ^The sq
36bd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36be0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36bf0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a  rns [SQLITE_OK].
36c00 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66  ** upon successf
36c10 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74  ul entry.  ^(Mut
36c20 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
36c30 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
36c40 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
36c50 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
36c60 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
36c70 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
36c80 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20  * In such cases 
36c90 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75  the,.** mutex mu
36ca0 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20  st be exited an 
36cb0 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  equal number of 
36cc0 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f  times before ano
36cd0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63  ther thread.** c
36ce0 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49  an enter.)^  ^(I
36cf0 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  f the same threa
36d00 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72  d tries to enter
36d10 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69   any other.** ki
36d20 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65  nd of mutex more
36d30 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20   than once, the 
36d40 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
36d50 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  fined..** SQLite
36d60 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
36d70 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
36d80 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
36d90 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29  use of mutexes.)
36da0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73  ^.**.** ^(Some s
36db0 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d  ystems (for exam
36dc0 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29  ple, Windows 95)
36dd0 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
36de0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
36df0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
36e00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36e10 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73  y().  On those s
36e20 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f  ystems, sqlite3_
36e30 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77  mutex_try().** w
36e40 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
36e50 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
36e60 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
36e70 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a  only ever uses.*
36e80 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
36e90 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69  try() as an opti
36ea0 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73  mization so this
36eb0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62   is acceptable b
36ec0 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a  ehavior.)^.**.**
36ed0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
36ee0 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74  tex_leave() rout
36ef0 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65  ine exits a mute
36f00 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72  x that was.** pr
36f10 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64  eviously entered
36f20 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
36f30 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68  ead.   ^(The beh
36f40 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
36f50 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74  fined if the mut
36f60 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  ex is not curren
36f70 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  tly entered by t
36f80 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68  he.** calling th
36f90 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63  read or is not c
36fa0 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
36fb0 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  ed.  SQLite will
36fc0 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
36fd0 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  her.)^.**.** ^If
36fe0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
36ff0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
37000 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f  nter(), sqlite3_
37010 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a  mutex_try(), or.
37020 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
37030 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55  _leave() is a NU
37040 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
37050 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69   all three routi
37060 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73  nes.** behave as
37070 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53   no-ops..**.** S
37080 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
37090 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
370a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
370b0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
370c0 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
370d0 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
370e0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
370f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37100 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
37110 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37120 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
37130 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
37140 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
37150 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
37160 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
37170 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
37180 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
37190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
371a0 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62  Mutex Methods Ob
371b0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
371c0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
371d0 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73  tructure defines
371e0 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72   the low-level r
371f0 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20  outines.** used 
37200 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20  to allocate and 
37210 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a  use mutexes..**.
37220 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20  ** Usually, the 
37230 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d  default mutex im
37240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72  plementations pr
37250 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65  ovided by SQLite
37260 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65   are.** sufficie
37270 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  nt, however the 
37280 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74  user has the opt
37290 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74  ion of substitut
372a0 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20  ing a custom.** 
372b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
372c0 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64  or specialized d
372d0 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79  eployments or sy
372e0 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20  stems for which 
372f0 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
37300 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69  ot provide a sui
37310 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
37320 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61  tion. In this ca
37330 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20  se, the user.** 
37340 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75  creates and popu
37350 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lates an instanc
37360 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
37370 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74  ure to pass.** t
37380 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
37390 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68  () along with th
373a0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
373b0 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  _MUTEX] option..
373c0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  ** Additionally,
373d0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
373e0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  this structure c
373f0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e  an be used as an
37400 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61  .** output varia
37410 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e  ble when queryin
37420 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72  g the system for
37430 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74   the current mut
37440 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
37450 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20  tion, using the 
37460 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
37470 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  ETMUTEX] option.
37480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
37490 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
374a0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
374b0 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
374c0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
374d0 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
374e0 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
374f0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
37500 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
37510 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20  ^The xMutexInit 
37520 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
37530 20 62 79 20 53 51 4c 69 74 65 20 65 78 61 63 74   by SQLite exact
37540 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
37550 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61  .** effective ca
37560 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69  ll to [sqlite3_i
37570 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  nitialize()]..**
37580 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45  .** ^The xMutexE
37590 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65  nd method define
375a0 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
375b0 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ure is invoked a
375c0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73  s.** part of sys
375d0 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20  tem shutdown by 
375e0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  the sqlite3_shut
375f0 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e  down() function.
37600 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   The.** implemen
37610 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  tation of this m
37620 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65  ethod is expecte
37630 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c  d to release all
37640 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20   outstanding.** 
37650 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e  resources obtain
37660 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20  ed by the mutex 
37670 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e  methods implemen
37680 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c  tation, especial
37690 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61  ly.** those obta
376a0 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74  ined by the xMut
376b0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20  exInit method.  
376c0 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29  ^The xMutexEnd()
376d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
376e0 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
376f0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
37700 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37710 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
37720 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69  ** ^(The remaini
37730 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73  ng seven methods
37740 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
37750 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74   structure (xMut
37760 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74  exAlloc,.** xMut
37770 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e  exFree, xMutexEn
37780 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20  ter, xMutexTry, 
37790 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75  xMutexLeave, xMu
377a0 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78  texHeld and.** x
377b0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d  MutexNotheld) im
377c0 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c  plement the foll
377d0 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
377e0 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a   (respectively):
377f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
37800 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37810 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c  mutex_alloc()] <
37820 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
37830 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66  [sqlite3_mutex_f
37840 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ree()] </li>.** 
37850 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
37860 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20  _mutex_enter()] 
37870 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
37880 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37890 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  try()] </li>.** 
378a0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
378b0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20  _mutex_leave()] 
378c0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
378d0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
378e0 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
378f0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37900 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
37910 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  )] </li>.** </ul
37920 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e  >)^.**.** The on
37930 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ly difference is
37940 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63   that the public
37950 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e   sqlite3_XXX fun
37960 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65  ctions enumerate
37970 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e  d.** above silen
37980 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69  tly ignore any i
37990 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20  nvocations that 
379a0 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  pass a NULL poin
379b0 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
379c0 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
379d0 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c  handle. The impl
379e0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
379f0 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  he methods defin
37a00 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74  ed.** by this st
37a10 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20  ructure are not 
37a20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64  required to hand
37a30 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68  le this case, th
37a40 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20  e results.** of 
37a50 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  passing a NULL p
37a60 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
37a70 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
37a80 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66  handle are undef
37a90 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74  ined.** (i.e. it
37aa0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74   is acceptable t
37ab0 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
37ac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
37ad0 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a   segfaults if.**
37ae0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
37af0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a  NULL pointer)..*
37b00 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49  *.** The xMutexI
37b10 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73  nit() method mus
37b20 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
37b30 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61    ^It must be ha
37b40 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76  rmless to.** inv
37b50 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29  oke xMutexInit()
37b60 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77   mutiple times w
37b70 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
37b80 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f  rocess and witho
37b90 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e  ut.** intervenin
37ba0 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65  g calls to xMute
37bb0 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20  xEnd().  Second 
37bc0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
37bd0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65  alls to.** xMute
37be0 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20  xInit() must be 
37bf0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78  no-ops..**.** ^x
37c00 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
37c10 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
37c20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37c30 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  n ([sqlite3_mall
37c40 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73  oc()].** and its
37c50 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e   associates).  ^
37c60 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65  Similarly, xMute
37c70 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f  xAlloc() must no
37c80 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d  t use SQLite mem
37c90 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
37ca0 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d  n for a static m
37cb0 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20  utex.  ^However 
37cc0 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61  xMutexAlloc() ma
37cd0 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20  y use SQLite.** 
37ce0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37cf0 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20  n for a fast or 
37d00 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e  recursive mutex.
37d10 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
37d20 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78  ill invoke the x
37d30 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f  MutexEnd() metho
37d40 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
37d50 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a  shutdown()] is.*
37d60 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e  * called, but on
37d70 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20  ly if the prior 
37d80 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e  call to xMutexIn
37d90 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  it returned SQLI
37da0 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75  TE_OK..** If xMu
37db0 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e  texInit fails in
37dc0 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20   any way, it is 
37dd0 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61  expected to clea
37de0 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c  n up after itsel
37df0 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65  f.** prior to re
37e00 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65  turning..*/.type
37e10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
37e20 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
37e30 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37e40 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
37e50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
37e60 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78  hods {.  int (*x
37e70 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29  MutexInit)(void)
37e80 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37e90 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71  End)(void);.  sq
37ea0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78  lite3_mutex *(*x
37eb0 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29  MutexAlloc)(int)
37ec0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
37ed0 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d  xFree)(sqlite3_m
37ee0 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
37ef0 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73  (*xMutexEnter)(s
37f00 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37f10 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54  .  int (*xMutexT
37f20 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ry)(sqlite3_mute
37f30 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
37f40 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69  MutexLeave)(sqli
37f50 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
37f60 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64  int (*xMutexHeld
37f70 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37f80 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37f90 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74  exNotheld)(sqlit
37fa0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a  e3_mutex *);.};.
37fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37fc0 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74   Mutex Verificat
37fd0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
37fe0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
37ff0 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20  utex_held() and 
38000 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
38010 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73  theld() routines
38020 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64  .** are intended
38030 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
38040 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
38050 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74  nts.  ^The SQLit
38060 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20  e core.** never 
38070 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
38080 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64  nes except insid
38090 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e  e an assert() an
380a0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  d applications.*
380b0 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f  * are advised to
380c0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64   follow the lead
380d0 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e   of the core.  ^
380e0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
380f0 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
38100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
38110 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
38120 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
38130 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
38140 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
38150 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61   flag.  ^Externa
38160 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  l mutex implemen
38170 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f  tations.** are o
38180 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20  nly required to 
38190 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f  provide these ro
381a0 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45  utines if SQLITE
381b0 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66  _DEBUG is.** def
381c0 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42  ined and if NDEB
381d0 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65  UG is not define
381e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
381f0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
38200 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
38210 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
38220 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
38230 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
38240 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
38250 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
38260 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  thread..**.** ^T
38270 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
38280 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
38290 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65  d to provided ve
382a0 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a  rsions of these.
382b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
382c0 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20   actually work. 
382d0 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  If the implement
382e0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70  ation does not p
382f0 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a  rovide working.*
38300 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  * versions of th
38310 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74  ese routines, it
38320 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74   should at least
38330 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74   provide stubs t
38340 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65  hat always.** re
38350 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61  turn true so tha
38360 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67  t one does not g
38370 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65  et spurious asse
38380 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a  rtion failures..
38390 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
383a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
383b0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
383c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
383d0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
383e0 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
383f0 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73 65 65  rn 1.   This see
38400 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  ms counter-intui
38410 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c  tive since.** cl
38420 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20  early the mutex 
38430 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69  cannot be held i
38440 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  f it does not ex
38450 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a  ist.  But the.**
38460 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20   the reason the 
38470 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65  mutex does not e
38480 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20  xist is because 
38490 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74  the build is not
384a0 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65  .** using mutexe
384b0 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f  s.  And we do no
384c0 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72  t want the asser
384d0 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  t() containing t
384e0 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  he.** call to sq
384f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
38500 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61  () to fail, so a
38510 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
38520 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f   is.** the appro
38530 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20  priate thing to 
38540 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  do.  ^The sqlite
38550 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
38560 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
38570 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
38580 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
38590 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
385a0 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47  /.#ifndef NDEBUG
385b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
385c0 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  ex_held(sqlite3_
385d0 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
385e0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
385f0 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
38600 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  *);.#endif../*.*
38610 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
38620 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68  x Types.**.** Th
38630 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
38640 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
38650 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
38660 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
38670 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
38680 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
38690 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  stants..**.** Th
386a0 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 20  e set of static 
386b0 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e  mutexes may chan
386c0 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69  ge from one SQLi
386d0 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  te release to th
386e0 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
386f0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ications that ov
38700 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c 74  erride the built
38710 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20  -in mutex logic 
38720 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61  must be.** prepa
38730 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61  red to accommoda
38740 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  te additional st
38750 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f  atic mutexes..*/
38760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38770 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20  MUTEX_FAST      
38780 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
38790 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
387a0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31  CURSIVE        1
387b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
387c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
387d0 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65  TER    2.#define
387e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
387f0 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33  ATIC_MEM       3
38800 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c    /* sqlite3_mal
38810 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  loc() */.#define
38820 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38830 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34  ATIC_MEM2      4
38840 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f    /* NOT USED */
38850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38860 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45  MUTEX_STATIC_OPE
38870 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c  N      4  /* sql
38880 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20  ite3BtreeOpen() 
38890 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
388a0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50  E_MUTEX_STATIC_P
388b0 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73  RNG      5  /* s
388c0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20  qlite3_random() 
388d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
388e0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
388f0 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c  RU       6  /* l
38900 72 75 20 70 61 67 65 20