/ Hex Artifact Content
Login

Artifact 16f33c1ceb971bfa7a04a73039947630f445146e:


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 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rsion.**.** Thes
10b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
10c0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
10d0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
10e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
10f0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
1110: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
1120: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1130: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
1140: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1150: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1180: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
1190: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
11a0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
11b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
11c0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
11d0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
11e0: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
11f0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
1200: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
1210: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
1220: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
1230: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
1240: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1250: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1260: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1270: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
1280: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
1290: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12a0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
12b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
12c0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
12d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
12e0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
12f0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
1300: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
1310: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
1320: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
1330: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1340: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1350: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1360: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1370: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1380: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1390: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
13a0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
13b0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
13c0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
13d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
1400: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
1410: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
1420: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1430: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
1440: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1450: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1460: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1470: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1480: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1490: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
14a0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
14b0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
14c0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
14d0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
14e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
14f0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
1500: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
1510: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
1520: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1530: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
1540: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1550: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 20 70 6f  () function a po
1560: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74  inter.** to a st
1570: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1580: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1590: 20 73 61 6d 65 20 61 73 20 74 68 65 20 5b 53 51   same as the [SQ
15a0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 0a  LITE_SOURCE_ID].
15b0: 2a 2a 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ** C preprocesso
15c0: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
15d0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
15e0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
15f0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
1600: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
1610: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1620: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1630: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1640: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1650: 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74  ion(void);.const
1660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1670: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69  ourceid(void);.i
1680: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
1690: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
16a0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
16b0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
16c0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
16d0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
16e0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16f0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1700: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1710: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1720: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1730: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1740: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1750: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1760: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1770: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1780: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1790: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
17a0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
17b0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
17c0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
17d0: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
17e0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
17f0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1800: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1810: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1820: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1830: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1840: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1850: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1860: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1870: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1880: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1890: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
18a0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
18b0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
18c0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
18d0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
18e0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
18f0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1900: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1910: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1920: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1930: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1940: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1950: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1960: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1970: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1980: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1990: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
19a0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
19b0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
19c0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
19d0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
19e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
19f0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1a00: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1a10: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1a20: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1a30: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1a40: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1a50: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1a60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1a70: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1a80: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1a90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1aa0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1ab0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1ac0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1ad0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1ae0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1af0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1b00: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1b10: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1b20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1b30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1b40: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1b50: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1b60: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1b70: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1b80: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1b90: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1ba0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1bb0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
1bc0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
1bd0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1be0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1bf0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1c00: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
1c10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1c20: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
1c30: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
1c40: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
1c50: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
1c60: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
1c70: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
1c80: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
1c90: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
1ca0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
1cb0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
1cc0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
1cd0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
1ce0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1cf0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1d00: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
1d10: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
1d20: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
1d30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
1d40: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
1d50: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
1d60: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
1d70: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
1d80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1d90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1da0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1db0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dc0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1dd0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
1de0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
1df0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e00: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
1e10: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
1e20: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
1e30: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
1e40: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
1e50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
1e60: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
1e70: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
1e80: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
1e90: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
1ea0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
1eb0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
1ec0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
1ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1ee0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ef0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
1f20: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
1f30: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
1f40: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
1f50: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
1f60: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
1f70: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
1f80: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
1f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
1fb0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1fc0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1fd0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1fe0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
1ff0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
2000: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
2010: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
2020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2030: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2040: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2050: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2060: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2070: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2080: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2090: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
20a0: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
20b0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
20c0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
20d0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
20e0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
20f0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
2100: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
2110: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
2120: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2130: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2140: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2150: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2160: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2170: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2180: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2190: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
21a0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
21b0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
21c0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
21d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
21f0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
2200: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2210: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
2220: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2230: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2240: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2250: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2260: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2270: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2280: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2290: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
22a0: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
22b0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
22c0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
22d0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
22e0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
22f0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2310: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2320: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2330: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2340: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2350: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2360: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2370: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2380: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2390: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
23a0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
23b0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
23c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
23d0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
23e0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
23f0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2400: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2410: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2420: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2430: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2440: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2450: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2460: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2470: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2480: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2490: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
24a0: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
24b0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
24c0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
24d0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
24e0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
24f0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2500: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2510: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2520: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2530: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2540: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2550: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2560: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2580: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2590: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
25a0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
25b0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
25c0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
25d0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
25e0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
25f0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2600: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64   successfullly d
2610: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
2620: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
2630: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2640: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
2650: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2660: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2670: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2680: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2690: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
26a0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
26b0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
26c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
26d0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
26e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
26f0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2700: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2710: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2720: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2730: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
2740: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2750: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2760: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2770: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2780: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2790: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
27a0: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
27b0: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
27c0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
27d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
27e0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
27f0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2800: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
2810: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
2820: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2830: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
2840: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2850: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2860: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2870: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
2880: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2890: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28a0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
28c0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
28d0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
28e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
28f0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2900: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2910: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
2920: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
2930: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
2950: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
2960: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68  terface.**.** Th
2a90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2aa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2ab0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
2ac0: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
2ad0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ae0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2af0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2b00: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b10: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
2b20: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b30: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
2b40: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
2b50: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
2b60: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
2b70: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
2b80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b90: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ba0: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
2bb0: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
2bc0: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
2bd0: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
2be0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
2bf0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
2c00: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
2c10: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
2c20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c30: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
2c40: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
2c50: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
2c60: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2c70: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
2c80: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
2c90: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
2ca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
2cb0: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
2cc0: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
2cd0: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
2ce0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
2cf0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
2d00: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
2d10: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  to.** to sqlite3
2d20: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
2d30: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
2d40: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
2d50: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
2d60: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
2d70: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
2d80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
2d90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
2da0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
2db0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
2dc0: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
2dd0: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
2de0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
2df0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
2e00: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
2e10: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
2e20: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
2e30: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
2e40: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
2e50: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
2e60: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
2e70: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
2e80: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
2e90: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
2ea0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
2eb0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
2ec0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
2ed0: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
2ee0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
2ef0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
2f00: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
2f10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f20: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
2f30: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
2f40: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2f50: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
2f60: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
2f70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
2f80: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
2f90: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
2fa0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2fb0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2fc0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2fd0: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
2fe0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
2ff0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3000: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3010: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3020: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3030: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3040: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3050: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3060: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3070: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3080: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3090: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
30a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
30b0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
30c0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
30d0: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
30e0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
30f0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3100: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3110: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3120: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3130: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3140: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3150: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3160: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3170: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3180: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3190: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
31a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
31b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
31c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
31d0: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
31e0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
31f0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3200: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3220: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3230: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3240: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3250: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3260: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3270: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3280: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3290: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
32a0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
32b0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
32c0: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
32d0: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
32e0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
32f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3300: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3320: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3330: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3340: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3350: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3360: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3370: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3380: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3390: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
33a0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
33b0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
33c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
33d0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
33e0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
33f0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3400: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3410: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3420: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3430: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3440: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3450: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3460: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3470: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3480: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3490: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
34a0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
34b0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
34c0: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
34d0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
34e0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
34f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3500: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3510: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3520: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3530: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3540: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3550: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3560: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3570: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3580: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3590: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
35a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
35c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
35d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
35e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
35f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3600: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3610: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3620: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3630: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3640: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3650: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3660: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3670: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3680: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3690: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
36a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
36b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
36d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3700: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3710: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3730: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3740: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3750: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3760: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3770: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3780: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3790: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
37a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
37d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
37e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
37f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3800: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3810: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3820: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3840: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3850: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3860: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3870: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3880: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3890: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
38a0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
38b0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
38c0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
38d0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
38e0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
38f0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3900: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3910: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3920: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3930: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3940: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3950: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3960: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3970: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3980: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3990: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
39a0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
39b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
39c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
39d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
39e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
39f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3a10: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3a20: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3a30: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3a50: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3a60: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3a70: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3a80: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3a90: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3aa0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
3ab0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
3ac0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3ad0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
3ae0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
3af0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
3b00: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
3b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3b20: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
3b30: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3b40: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
3b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b60: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
3b70: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
3b80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
3b90: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
3ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
3bb0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
3bc0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
3bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3be0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
3bf0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
3c00: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
3c10: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
3c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
3c30: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
3c40: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
3c50: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
3c60: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3c80: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
3c90: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
3ca0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
3cb0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
3cc0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
3cd0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
3ce0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
3cf0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
3d00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3d10: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
3d20: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
3d30: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
3d40: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
3d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
3d60: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
3d70: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
3d80: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
3d90: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
3da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
3db0: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
3dc0: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
3dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
3de0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3df0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
3e00: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
3e10: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
3e20: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
3e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3e40: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
3e50: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
3e60: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
3e70: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
3e80: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
3e90: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
3ea0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
3eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
3ec0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
3ed0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
3ee0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
3ef0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
3f10: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
3f20: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
3f30: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
3f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
3f50: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
3f60: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
3f70: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
3f80: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
3f90: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
3fa0: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
3fb0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
3fc0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
3fd0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
3fe0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
3ff0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4010: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
4020: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
4030: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
4050: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
4060: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4070: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4090: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
40a0: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
40b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
40c0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
40d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40e0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
40f0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4100: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
4110: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4130: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4140: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4150: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4160: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4180: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4190: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
41a0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
41b0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
41c0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
41d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
41e0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
41f0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4200: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
4220: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
4230: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4240: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4250: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4260: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4270: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4280: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4290: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
42a0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
42b0: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
42c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
42d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
42e0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
42f0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4300: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
4310: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
4320: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
4330: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
4340: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
4350: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4360: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4370: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4380: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4390: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
43a0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
43b0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
43c0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
43d0: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
43e0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
43f0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4400: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
4410: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
4420: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
4430: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
4440: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
4450: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4460: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4470: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4480: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
44a0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
44b0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
44c0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
44d0: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
44e0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
44f0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4500: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4510: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4520: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4530: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4550: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4560: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4570: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4580: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4590: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
45a0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
45b0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
45c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
45d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
45e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
45f0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4600: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4610: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4620: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4630: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4650: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4660: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4670: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4690: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
46a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
46b0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
46d0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
46e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
46f0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4700: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4710: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4730: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4750: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4760: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4770: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4780: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4790: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
47a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
47b0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
47c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
47d0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
47e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
47f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4800: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4810: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4840: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4850: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4860: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4880: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
48a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
48b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
48c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
48d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
48e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
48f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4900: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4910: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4920: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4940: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4950: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4960: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4980: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4990: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
49a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
49b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
49c0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
49d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
49e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
49f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a00: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4a10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4a30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a40: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4a50: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4a60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4a70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a80: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4a90: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4aa0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4ab0: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4ac0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4ad0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4ae0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
4af0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4b00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4b10: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4b20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4b30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
4b40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
4b50: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
4b60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4b70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
4b80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4b90: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
4bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
4bd0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4be0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c00: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
4c10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
4c20: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4c30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c50: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
4c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
4c70: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4c80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ca0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
4cb0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
4cc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
4cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
4d00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d20: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
4d30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
4d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
4d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
4d80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4da0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
4db0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
4dc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4de0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
4df0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
4e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e20: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
4e30: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
4e40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e60: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
4e70: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
4e80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ea0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
4eb0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
4ec0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ee0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
4ef0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
4f00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f20: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
4f30: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
4f40: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4f50: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f70: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
4f80: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
4f90: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fc0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
4fd0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
4fe0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4ff0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5010: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5020: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5030: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5040: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5050: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5060: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5070: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5080: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5090: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
50a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
50b0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
50c0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
50d0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
50e0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
50f0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
5100: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
5110: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
5120: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
5130: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5140: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5150: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5160: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5170: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5190: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
51a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
51b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
51c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
51d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
51e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
51f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
5200: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5210: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5220: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5230: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5240: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5250: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5260: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5270: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5280: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5290: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
52a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
52b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
52c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
52d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
52e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
52f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
5300: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5310: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5320: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5330: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5340: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5350: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5360: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5370: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5380: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5390: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
53a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
53b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
53e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5440: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5460: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5470: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
54a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
54b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
54d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
54e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5500: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5530: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5560: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5590: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
55a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55b0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
55c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
55d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
55e0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
55f0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
5600: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
5610: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5620: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5630: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
5640: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
5650: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
5660: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
5670: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
5680: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5690: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
56b0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
56c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
56d0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
56e0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
56f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5700: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
5710: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
5720: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5740: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
5750: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
5760: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
5770: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
5780: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5790: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
57a0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
57b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
57c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
57d0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
57e0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
57f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5800: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5810: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5820: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5830: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5840: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5850: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5860: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5870: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5880: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5890: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
58a0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
58b0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
58c0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
58d0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
58e0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
58f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5900: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
5910: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5920: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
5930: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5940: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5950: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5960: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
5970: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
5980: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5990: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
59a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
59b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
59c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
59d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
59e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
59f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5a00: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5a10: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5a20: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5a30: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5a40: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5a50: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
5a60: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5a70: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
5a80: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
5a90: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
5aa0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
5ab0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
5ac0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5ad0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
5ae0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5af0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5b00: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5b10: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5b20: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5b30: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
5b40: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
5b50: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
5b60: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
5b70: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5b80: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
5b90: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
5ba0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
5bb0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
5bc0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
5bd0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5be0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
5bf0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
5c00: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
5c10: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
5c20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c30: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
5c40: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
5c50: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
5c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5c70: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
5c80: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
5c90: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
5ca0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
5cb0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
5cc0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
5cd0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
5ce0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
5cf0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
5d00: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
5d10: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
5d20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
5d30: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
5d40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
5d50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
5d60: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
5d70: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
5d80: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
5d90: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5da0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
5db0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
5dc0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
5dd0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
5de0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
5df0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f  .**.** If the xO
5e00: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20  pen method sets 
5e10: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
5e20: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
5e30: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
5e40: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
5e50: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
5e60: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
5e70: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
5e80: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
5e90: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72   the xOpen repor
5ea0: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
5eb0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
5ec0: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
5ed0: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
5ee0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
5ef0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20  led xOpen.** is 
5f00: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f  for the xOpen to
5f10: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
5f20: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
5f30: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a  lement to NULL..
5f40: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
5f50: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
5f60: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
5f70: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
5f80: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
5f90: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
5fa0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
5fb0: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
5fc0: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
5fd0: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
5fe0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
5ff0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
6000: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
6010: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
6020: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
6030: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
6040: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
6050: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
6060: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
6070: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
6080: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
6090: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
60a0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
60b0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
60c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
60d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
60e0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
60f0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
6100: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6110: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6120: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6130: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6140: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6150: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6160: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
6170: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
6180: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
6190: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
61a0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
61b0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
61c0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
61d0: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
61e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
61f0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
6200: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
6210: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
6220: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
6230: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6240: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6250: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
6260: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
6270: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
6280: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
6290: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
62a0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
62b0: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
62c0: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
62d0: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
62e0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
62f0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
6300: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
6310: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
6320: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
6330: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6340: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6350: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6360: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6370: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
6380: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6390: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
63a0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
63b0: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
63c0: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
63d0: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
63e0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
63f0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
6400: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
6410: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
6420: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
6430: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6440: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6450: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6460: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6470: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6480: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
6490: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
64a0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
64b0: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
64c0: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
64d0: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
64e0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
64f0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
6500: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
6510: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
6520: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
6530: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6540: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6550: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
6560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6570: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6580: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6590: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
65a0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
65b0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
65c0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
65d0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
65e0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
65f0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
6600: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
6610: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
6620: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
6630: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6640: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6650: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
6660: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
6670: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6680: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
6690: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
66a0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
66b0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
66c0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
66d0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
66e0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
66f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6700: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
6710: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
6720: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
6730: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
6740: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
6750: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
6780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6790: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
67a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
67c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
67e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
6800: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6810: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
6820: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6830: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
6840: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6850: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6860: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6870: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6880: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6890: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
68a0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
68b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
68c0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
68d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
68e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
68f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6900: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6910: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6920: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6940: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6950: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6960: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6970: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6980: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6990: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
69a0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
69b0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
69c0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
69d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
69e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
69f0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6a00: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6a10: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6a20: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6a30: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6a40: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6a50: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6a60: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6a70: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6a80: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6a90: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6aa0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6ab0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6ac0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6ad0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6ae0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6af0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6b00: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
6b10: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
6b20: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
6b30: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
6b40: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
6b50: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
6b60: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
6b70: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
6b80: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
6b90: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
6ba0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
6bb0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
6bc0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
6bd0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
6be0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
6bf0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
6c00: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
6c10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
6c20: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
6c30: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
6c40: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
6c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
6c60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6c70: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
6c80: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
6c90: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
6ca0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6cb0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6cc0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6cd0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6ce0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6cf0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6d00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6d10: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6d20: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6d30: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
6d40: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
6d50: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
6d60: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
6d70: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
6d80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6d90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
6da0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
6db0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6dc0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6dd0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6de0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6df0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6e00: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6e10: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6e20: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6e30: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
6e40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
6e50: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
6e60: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
6e70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6e80: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
6e90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
6ea0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
6eb0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6ec0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6ed0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
6ee0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
6ef0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
6f00: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
6f10: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
6f20: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6f30: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
6f40: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
6f50: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
6f60: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6f70: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
6f80: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
6f90: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
6fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6fb0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6fc0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
6fd0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6fe0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
6ff0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
7000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7010: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
7020: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
7030: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7040: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7050: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7060: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7070: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7080: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7090: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
70a0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
70b0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
70c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
70d0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
70e0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
70f0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
7100: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
7110: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
7120: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
7130: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7140: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7150: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
7160: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
7170: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
7180: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
7190: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
71a0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
71b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
71c0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
71d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
71e0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
71f0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
7200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
7210: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
7220: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
7230: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
7240: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
7250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7260: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
7270: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
7280: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
7290: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
72a0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
72b0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
72c0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
72d0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
72e0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
72f0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
7300: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
7310: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
7320: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
7330: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
7340: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
7350: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
7360: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
7370: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
7380: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
7390: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
73a0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
73b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
73c0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
73d0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
73e0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
73f0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
7400: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
7410: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7420: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7430: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
7440: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
7450: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
7460: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
7470: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
7480: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
7490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
74a0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
74b0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
74c0: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
74d0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
74e0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
74f0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
7500: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
7510: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
7520: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
7530: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7540: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
7550: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
7560: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
7570: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
7580: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
7590: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
75a0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
75b0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
75c0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
75d0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
75e0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
75f0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
7600: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
7610: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
7620: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
7630: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
7640: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
7650: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7660: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
7670: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
7680: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
7690: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
76a0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
76b0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
76c0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
76d0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
76e0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
76f0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
7700: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
7710: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
7720: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
7730: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
7740: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
7750: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
7760: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
7770: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
7780: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
7790: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
77a0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
77b0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
77c0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
77d0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
77e0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
77f0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
7800: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
7810: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7820: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
7830: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7840: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7850: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7860: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7870: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
7880: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
7890: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
78a0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
78b0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
78c0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
78d0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
78e0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
78f0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
7900: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
7910: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
7920: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
7930: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
7940: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
7950: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
7960: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
7970: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
7980: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
7990: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
79a0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
79b0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
79c0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
79d0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
79e0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
79f0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
7a00: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
7a10: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
7a20: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
7a30: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
7a40: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
7a50: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
7a60: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
7a70: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
7a80: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
7a90: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
7aa0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
7ab0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
7ac0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
7ad0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
7ae0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
7af0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
7b00: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
7b10: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
7b20: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
7b30: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
7b40: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
7b50: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
7b60: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
7b70: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
7b80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7b90: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
7ba0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
7bb0: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
7bc0: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
7bd0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
7be0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
7bf0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
7c00: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7c10: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
7c20: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
7c30: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
7c40: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
7c50: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
7c60: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
7c70: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
7c80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7c90: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
7ca0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
7cb0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
7cc0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
7cd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
7ce0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
7cf0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
7d00: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
7d10: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
7d20: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
7d30: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
7d40: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7d50: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
7d60: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
7d70: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
7d80: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
7d90: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
7da0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
7db0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
7dc0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
7dd0: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
7de0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
7df0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  et..**.** SQLite
7e00: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
7e10: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
7e20: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7e30: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
7e40: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
7e50: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
7e60: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
7e70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
7e80: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
7e90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7ea0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
7eb0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7ec0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
7ed0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
7ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
7ef0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7f00: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7f10: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
7f20: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7f30: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
7f40: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7f50: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
7f60: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
7f70: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
7f80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7f90: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
7fa0: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
7fb0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
7fc0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
7fd0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
7fe0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
7ff0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
8000: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
8010: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
8020: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
8030: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8040: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8050: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8060: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8070: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8080: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8090: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
80a0: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
80b0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
80c0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
80d0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
80e0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
80f0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
8100: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8110: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
8120: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
8130: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8140: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8150: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8160: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8170: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8180: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8190: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
81a0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
81b0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
81c0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
81d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
81f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8200: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8210: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
8220: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8230: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8240: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8250: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8260: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8270: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8280: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51  closed.  The [SQ
8290: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
82a0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
82b0: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
82c0: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
82d0: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
82e0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
82f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8300: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
8310: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
8320: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
8330: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
8340: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8350: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
8360: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
8370: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
8380: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
8390: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
83a0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
83b0: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
83c0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
83d0: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
83e0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
83f0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
8400: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
8410: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
8420: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
8430: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
8440: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
8450: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
8460: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
8470: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
8480: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
8490: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
84a0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
84b0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
84c0: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74  access..**.** At
84d0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
84e0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
84f0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
8500: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
8510: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
8520: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
8530: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8540: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8550: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8560: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8570: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8580: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8590: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
85a0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
85b0: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
85c0: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
85d0: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
85e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
85f0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
8600: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
8610: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8620: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
8630: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
8640: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
8650: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
8660: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
8670: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
8680: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
8690: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
86a0: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
86b0: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
86c0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
86d0: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
86e0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
86f0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54  en call..**.** T
8700: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8710: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
8720: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
8730: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8740: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8750: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8760: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
8770: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8780: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
8790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
87a0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
87b0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
87c0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
87d0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
87e0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
87f0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
8800: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
8810: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
8820: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
8830: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
8840: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
8850: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
8860: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
8870: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
8880: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
8890: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
88a0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
88b0: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
88c0: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
88d0: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
88e0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
88f0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
8900: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
8910: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
8920: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
8930: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
8940: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
8950: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
8960: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
8970: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8980: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
8990: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
89a0: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
89b0: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
89c0: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
89d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
89e0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
89f0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
8a00: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
8a10: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
8a20: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
8a30: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
8a40: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
8a50: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
8a60: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
8a70: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
8a80: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8a90: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
8aa0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
8ab0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
8ac0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
8ad0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
8ae0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
8af0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
8b00: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
8b10: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
8b20: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
8b30: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
8b40: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
8b50: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
8b60: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
8b70: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
8b80: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
8b90: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
8ba0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
8bb0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
8bc0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
8bd0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
8be0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
8bf0: 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79  d time..**.*/.ty
8c00: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8c10: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
8c20: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
8c30: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
8c40: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
8c50: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
8c60: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
8c70: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
8c80: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
8c90: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
8ca0: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
8cb0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
8cc0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
8cd0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
8ce0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
8cf0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
8d00: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
8d10: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
8d20: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
8d30: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
8d40: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
8d50: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
8d60: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
8d70: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
8d80: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
8d90: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
8da0: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
8db0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
8dc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8dd0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8de0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
8df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
8e00: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
8e10: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
8e20: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
8e30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8e40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
8e50: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
8e60: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
8e70: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8e80: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
8e90: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
8ea0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8eb0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
8ec0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8ed0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
8ee0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
8ef0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
8f00: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
8f10: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8f20: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
8f30: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
8f40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8f50: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
8f60: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
8f70: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
8f80: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
8f90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
8fa0: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
8fb0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
8fc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8fd0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
8fe0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
8ff0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
9000: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
9010: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
9020: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9030: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9040: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9050: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9060: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9070: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9080: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9090: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
90a0: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69   *);.  /* New fi
90b0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
90c0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
90d0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
90e0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
90f0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
9100: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
9110: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f  appens. */.};../
9120: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9130: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9140: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
9150: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
9160: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9170: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9180: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
9190: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
91a0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
91b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
91c0: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
91d0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
91e0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
91f0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9200: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9210: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
9220: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
9230: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
9240: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
9250: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9260: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
9270: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9280: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
9290: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
92a0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
92b0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
92c0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
92d0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
92e0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
92f0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
9300: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9310: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9320: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
9330: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9340: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9350: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9360: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9370: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9380: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9390: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
93a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
93b0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
93c0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
93d0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
93e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
93f0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
9400: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
9410: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
9420: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9430: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
9440: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
9450: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
9460: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
9470: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9480: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
9490: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
94a0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
94b0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
94c0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
94d0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
94e0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
94f0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
9500: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
9510: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
9520: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
9530: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
9540: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9550: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9560: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9570: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9580: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9590: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
95a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
95b0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
95c0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
95d0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
95e0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
95f0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
9600: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9610: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9620: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
9630: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
9640: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9650: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
9660: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
9670: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9680: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
9690: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
96a0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
96b0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
96c0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
96d0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
96e0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
96f0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9700: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
9710: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
9720: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9730: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
9740: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
9750: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
9760: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
9770: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9780: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
9790: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
97a0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
97b0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
97c0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
97d0: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
97e0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
97f0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
9800: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
9810: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
9820: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
9830: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
9840: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
9850: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
9860: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
9870: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
9880: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
9890: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
98a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
98b0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
98c0: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
98d0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
98e0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
98f0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
9900: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
9910: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9920: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
9930: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
9940: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9950: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
9960: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9970: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9980: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
9990: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
99a0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
99b0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
99c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
99d0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
99e0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
99f0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
9a00: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
9a10: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
9a20: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
9a30: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
9a40: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
9a50: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
9a60: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
9a70: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
9a80: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
9a90: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
9aa0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
9ab0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
9ac0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
9ad0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
9ae0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9af0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9b00: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9b10: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9b20: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9b30: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9b40: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9b50: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9b60: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9b70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9b80: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9b90: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9ba0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9bb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9bc0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9bd0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9be0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9bf0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9c00: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9c10: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9c20: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9c30: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9c40: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
9c50: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
9c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
9c70: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
9c80: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
9c90: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
9ca0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
9cb0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
9cc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9cd0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
9ce0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
9cf0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
9d00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9d10: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
9d20: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
9d30: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
9d40: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
9d50: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
9d60: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
9d70: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
9d80: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
9d90: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
9da0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
9db0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
9dc0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
9dd0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
9de0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
9df0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
9e00: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
9e10: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
9e20: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
9e30: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
9e40: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
9e50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
9e60: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
9e70: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
9e80: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
9e90: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
9ea0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
9eb0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
9ec0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
9ed0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
9ee0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
9ef0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
9f00: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
9f10: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
9f20: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
9f30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
9f40: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
9f50: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
9f60: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
9f70: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
9f80: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
9f90: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
9fa0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
9fb0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
9fc0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
9fd0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
9fe0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
9ff0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
a000: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
a010: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
a020: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
a030: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
a040: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a050: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
a060: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
a070: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
a080: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a090: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
a0a0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a0b0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
a0c0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
a0d0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
a0e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
a0f0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
a100: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
a110: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
a120: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
a130: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
a140: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
a150: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
a160: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
a170: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
a180: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
a190: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
a1a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a1b0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
a1c0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a1d0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
a1e0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
a1f0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a200: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
a210: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
a220: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
a230: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
a240: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
a250: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
a260: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
a270: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
a280: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
a290: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
a2a0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a2b0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a2c0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a2d0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a2e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a2f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a300: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a310: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a320: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a330: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a340: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a350: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a360: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a370: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
a380: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a390: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
a3a0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
a3b0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
a3c0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a3d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
a3e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
a3f0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
a400: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
a410: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
a420: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
a430: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
a440: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
a450: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
a460: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
a470: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a480: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a490: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a4a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a4b0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a4c0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a4d0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a4e0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a4f0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a500: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a510: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a520: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a530: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a540: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a550: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a560: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a570: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a580: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a590: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a5a0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a5b0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a5c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a5d0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a5e0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a5f0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a600: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a610: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a620: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a630: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a640: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a650: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a660: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a670: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a680: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a690: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a6a0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a6b0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a6c0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a6d0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a6e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
a6f0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
a700: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
a710: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
a720: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a730: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
a740: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
a750: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
a760: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
a770: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
a780: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
a790: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
a7a0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
a7b0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
a7c0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
a7d0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
a7e0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
a7f0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
a800: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
a810: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
a820: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
a830: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
a840: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a850: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
a860: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
a870: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a880: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a890: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
a8a0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
a8b0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
a8c0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
a8d0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
a8e0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
a8f0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
a900: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
a910: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
a920: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
a930: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
a940: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
a950: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
a960: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a970: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a980: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a990: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a9a0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
a9b0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
a9c0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
a9d0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
a9e0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
a9f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
aa00: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
aa10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
aa20: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
aa30: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
aa40: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
aa50: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
aa60: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
aa70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
aa80: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ns.** EXPERIMENT
aa90: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  AL.**.** The sql
aaa0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
aab0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
aac0: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
aad0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
aae0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
aaf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
ab00: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
ab10: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
ab20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ab30: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
ab40: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
ab50: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
ab60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ab70: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
ab80: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ab90: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
aba0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
abb0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
abc0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
abd0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
abe0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
abf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
ac00: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
ac10: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ac20: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
ac30: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
ac40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
ac50: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
ac60: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ac70: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ac80: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
ac90: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
aca0: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
acb0: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
acc0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
acd0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
ace0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
acf0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
ad00: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
ad10: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
ad20: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
ad30: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
ad40: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
ad50: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
ad60: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
ad70: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
ad80: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
ad90: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
ada0: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
adb0: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
adc0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
add0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
ade0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
adf0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
ae00: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
ae10: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
ae20: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
ae30: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
ae40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ae50: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
ae60: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
ae70: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
ae80: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
ae90: 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45 52 49  utines.** EXPERI
aea0: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
aeb0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
aec0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
aed0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
aee0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
aef0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
af00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
af10: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
af20: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
af30: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
af40: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
af50: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
af60: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
af70: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
af80: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
af90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
afa0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
afb0: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
afc0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
afd0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
afe0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
aff0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
b000: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
b010: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
b020: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b030: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
b040: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
b050: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b060: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b070: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
b080: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
b090: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
b0a0: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
b0b0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
b0c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
b0d0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
b0e0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
b0f0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
b100: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
b110: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
b120: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
b130: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
b140: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
b150: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
b160: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
b170: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
b180: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
b190: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
b1a0: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
b1b0: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
b1c0: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
b1d0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
b1e0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
b1f0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
b200: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
b210: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
b220: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
b230: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
b240: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
b250: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
b260: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
b270: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
b280: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b290: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
b2a0: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
b2b0: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
b2c0: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
b2d0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
b2e0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
b2f0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
b300: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
b310: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
b320: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
b330: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
b340: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
b350: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
b360: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
b370: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
b380: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c  ry..** The xReal
b390: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  loc method must 
b3a0: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f  work like reallo
b3b0: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61  c() from the sta
b3c0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a  ndard C library.
b3d0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65  ** with the exce
b3e0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68  ption that if th
b3f0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b400: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73  t to xRealloc is
b410: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c   zero,.** xReall
b420: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d  oc must be a no-
b430: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74  op - it must not
b440: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c   perform any all
b450: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65  ocation or.** de
b460: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51  allocation.  ^SQ
b470: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
b480: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
b490: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
b4a0: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
b4b0: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
b4c0: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
b4d0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
b4e0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73  ** And so in cas
b4f0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75  es where xRoundu
b500: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  p always returns
b510: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
b520: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  er,.** xRealloc 
b530: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63  can perform exac
b540: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64  tly as the stand
b550: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c  ard library real
b560: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69  loc() and.** sti
b570: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61  ll be in complia
b580: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70  nce with this sp
b590: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  ecification..**.
b5a0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
b5b0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
b5c0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
b5d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b5e0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
b5f0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
b600: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
b610: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
b620: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
b630: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
b640: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
b650: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
b660: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
b670: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
b680: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
b690: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
b6a0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
b6b0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
b6c0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
b6d0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
b6e0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
b6f0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
b700: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b710: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b720: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
b730: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
b740: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
b750: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b760: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
b770: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
b780: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
b790: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
b7a0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
b7b0: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
b7c0: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
b7d0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
b7e0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
b7f0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
b800: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
b810: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
b820: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
b830: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
b840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b850: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
b860: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
b870: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
b880: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b890: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
b8a0: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
b8b0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
b8c0: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
b8d0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
b8e0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
b8f0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
b900: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
b910: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
b920: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
b930: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
b940: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
b950: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
b960: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
b970: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
b980: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
b990: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
b9a0: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
b9b0: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
b9c0: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
b9d0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
b9e0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
b9f0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
ba00: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
ba10: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
ba20: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
ba30: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
ba40: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
ba50: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
ba60: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
ba70: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
ba80: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ba90: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
baa0: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
bab0: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
bac0: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
bad0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
bae0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
baf0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
bb00: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
bb10: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
bb20: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
bb30: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
bb40: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bb50: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
bb60: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
bb70: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
bb80: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
bb90: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
bba0: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
bbb0: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
bbc0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
bbd0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
bbe0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
bbf0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
bc00: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
bc10: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
bc20: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
bc30: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
bc40: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
bc50: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
bc60: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
bc70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
bc80: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
bc90: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
bca0: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
bcb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
bcc0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bcd0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
bce0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
bcf0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bd00: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
bd10: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
bd20: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
bd30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
bd40: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
bd50: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
bd60: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
bd70: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
bd80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
bd90: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
bda0: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
bdb0: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
bdc0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
bdd0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
bde0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
bdf0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
be00: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
be10: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
be20: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
be30: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
be40: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
be50: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
be60: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
be70: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
be80: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
be90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
bea0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
beb0: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
bec0: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
bed0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
bee0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
bef0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
bf00: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
bf10: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
bf20: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
bf30: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
bf40: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
bf50: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
bf60: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
bf70: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
bf80: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
bf90: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
bfa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bfb0: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
bfc0: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
bfd0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bfe0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
bff0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
c000: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
c010: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c020: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
c030: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
c040: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
c050: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
c060: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c070: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
c080: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
c090: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
c0a0: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
c0b0: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
c0c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c0d0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
c0e0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
c0f0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
c100: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
c110: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
c120: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
c130: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
c140: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
c150: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
c160: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c170: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
c180: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
c190: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c1a0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
c1b0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
c1c0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
c1d0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
c1e0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
c1f0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
c200: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
c210: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
c220: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
c230: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
c240: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
c250: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
c260: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
c270: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
c280: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
c290: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
c2a0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
c2b0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
c2c0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
c2d0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
c2e0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
c2f0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
c300: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
c310: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
c320: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
c330: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
c340: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
c350: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
c360: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
c370: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
c380: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
c390: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
c3a0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
c3b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c3c0: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
c3d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c3e0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
c3f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c400: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
c410: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
c420: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
c430: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
c440: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
c450: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
c460: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
c470: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
c480: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
c490: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
c4a0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
c4b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c4c0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c4d0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
c4e0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c4f0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
c500: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
c510: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
c520: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c530: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
c540: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
c550: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
c560: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
c570: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
c580: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
c590: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
c5a0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
c5b0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
c5c0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
c5d0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
c5e0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
c5f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c600: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
c610: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
c620: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
c630: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
c640: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
c650: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
c660: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
c670: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
c680: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
c690: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
c6a0: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
c6b0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
c6c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c6d0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
c6e0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
c6f0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
c700: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
c710: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
c720: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c730: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
c740: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c750: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
c760: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c770: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c780: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c790: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
c7a0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
c7b0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
c7c0: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
c7d0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
c7e0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
c7f0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
c800: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
c810: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
c820: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
c830: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
c840: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
c850: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
c860: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
c870: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
c880: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
c890: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
c8a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
c8b0: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
c8c0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
c8d0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
c8e0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
c8f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c900: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
c910: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
c920: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
c930: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
c940: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
c950: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
c960: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
c970: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
c980: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
c990: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
c9a0: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
c9b0: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
c9c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c9d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
c9e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
c9f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ca00: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ca10: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
ca20: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
ca30: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
ca40: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
ca50: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
ca60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ca70: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
ca80: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
ca90: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
caa0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
cab0: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
cac0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
cad0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
cae0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
caf0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
cb00: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
cb10: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
cb20: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
cb30: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
cb40: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
cb50: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
cb60: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
cb70: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
cb80: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
cb90: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
cba0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
cbb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
cbc0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
cbd0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
cbe0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
cbf0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
cc00: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
cc10: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
cc20: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
cc30: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
cc40: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
cc50: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
cc60: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
cc70: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
cc80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
cc90: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
cca0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ccb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
ccc0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
ccd0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
cce0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ccf0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
cd00: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
cd10: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
cd20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
cd30: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
cd40: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
cd50: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
cd60: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
cd70: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
cd80: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
cd90: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
cda0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
cdb0: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
cdc0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
cdd0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
cde0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
cdf0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
ce00: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
ce10: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
ce20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ce30: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
ce40: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
ce50: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
ce60: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
ce70: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ce80: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
ce90: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
cea0: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
ceb0: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
cec0: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
ced0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
cee0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
cef0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
cf00: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
cf10: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
cf20: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
cf30: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
cf40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
cf50: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
cf60: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
cf70: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
cf80: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
cf90: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
cfa0: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
cfb0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
cfc0: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
cfd0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
cfe0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
cff0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
d000: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
d010: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
d020: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
d030: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
d040: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
d050: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
d060: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
d070: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
d080: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
d090: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
d0a0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
d0b0: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
d0c0: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
d0d0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
d0e0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d0f0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
d100: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
d110: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d120: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
d130: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
d140: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
d150: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
d160: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
d170: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
d180: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
d190: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
d1a0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
d1b0: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
d1c0: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
d1d0: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
d1e0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63   which the scrac
d1f0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
d200: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
d210: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
d220: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
d230: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
d240: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
d250: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
d260: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
d270: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
d280: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
d290: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
d2a0: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
d2b0: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
d2c0: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
d2d0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
d2e0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
d2f0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74  uired due to int
d300: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a  ernal overhead..
d310: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
d320: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d330: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
d340: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
d350: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
d360: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
d370: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
d380: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
d390: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
d3a0: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72  ratch buffer per
d3b0: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
d3c0: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
d3d0: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
d3e0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
d3f0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c  f threads.  ^SQL
d400: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
d410: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
d420: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
d430: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74  is more than 6 t
d440: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
d450: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20  e.** page size. 
d460: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
d470: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
d480: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  l scratch memory
d490: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74   beyond .** what
d4a0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
d4b0: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
d4c0: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
d4d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
d4e0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
d4f0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
d500: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
d510: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d520: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
d530: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
d540: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
d550: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
d560: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
d570: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
d580: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
d590: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
d5a0: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
d5b0: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
d5c0: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e  e implemenation.
d5d0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
d5e0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
d5f0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
d600: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
d610: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
d620: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d630: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
d640: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
d650: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f  FIG_PCACHE optio
d660: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
d670: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
d680: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
d690: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
d6a0: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
d6b0: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
d6c0: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
d6d0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
d6e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
d6f0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
d700: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d710: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
d720: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
d730: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
d740: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
d750: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
d760: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
d770: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
d780: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
d790: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
d7a0: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
d7b0: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
d7c0: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
d7d0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
d7e0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
d7f0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
d800: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
d810: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
d820: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
d830: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
d840: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d850: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
d860: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
d870: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
d880: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
d890: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d8a0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
d8b0: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
d8c0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
d8d0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
d8e0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
d8f0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
d900: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
d910: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
d920: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
d930: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
d940: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
d950: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
d960: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
d970: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
d980: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
d990: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
d9a0: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
d9b0: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  space..** ^The i
d9c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d9d0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
d9e0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
d9f0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
da00: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
da10: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
da20: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
da30: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
da40: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
da50: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
da60: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
da70: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
da80: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
da90: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
daa0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
dab0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
dac0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
dad0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
dae0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
daf0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
db00: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
db10: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
db20: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
db30: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
db40: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
db50: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
db60: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
db70: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
db80: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
db90: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
dba0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
dbb0: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
dbc0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
dbd0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
dbe0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
dbf0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
dc00: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
dc10: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
dc20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
dc30: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
dc40: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
dc50: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
dc60: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
dc70: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
dc80: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
dc90: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
dca0: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
dcb0: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
dcc0: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
dcd0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
dce0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
dcf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
dd00: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
dd10: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
dd20: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
dd30: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
dd40: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
dd50: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
dd60: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
dd70: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
dd80: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
dd90: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
dda0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
ddb0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
ddc0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
ddd0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
dde0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
ddf0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
de00: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
de10: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
de20: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
de30: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
de40: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
de50: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
de60: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
de70: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
de80: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
de90: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
dea0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
deb0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
dec0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
ded0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
dee0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
def0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
df00: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
df10: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
df20: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
df30: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
df40: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
df50: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
df60: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
df70: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
df80: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
df90: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
dfa0: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
dfb0: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
dfc0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
dfd0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
dfe0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
dff0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
e000: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
e010: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
e020: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
e030: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
e040: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
e050: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
e060: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e070: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
e080: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
e090: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
e0a0: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
e0b0: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
e0c0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
e0d0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
e0e0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e0f0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
e100: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
e110: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
e120: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
e130: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e140: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
e150: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e160: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e170: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e180: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e190: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e1a0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e1b0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
e1c0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e1d0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
e1e0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e1f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e200: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e210: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e220: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
e230: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
e240: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
e250: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
e260: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
e270: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
e280: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
e290: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
e2a0: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
e2b0: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
e2c0: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
e2d0: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
e2e0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
e2f0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e300: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e310: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
e320: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e330: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
e340: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
e350: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
e360: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
e370: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
e380: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
e390: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
e3a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e3b0: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
e3c0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
e3d0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
e3e0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
e3f0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e400: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
e410: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e420: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
e430: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
e440: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
e450: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
e460: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
e470: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
e480: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
e490: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
e4a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
e4b0: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
e4c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
e4d0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
e4e0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
e4f0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
e500: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
e510: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
e520: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e530: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
e540: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
e550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e560: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
e570: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
e580: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
e590: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
e5a0: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
e5b0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
e5c0: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
e5d0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
e5e0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
e5f0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
e600: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
e610: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
e620: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
e630: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
e640: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
e650: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
e660: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
e670: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
e680: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
e690: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
e6a0: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
e6b0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
e6c0: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
e6d0: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
e6e0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
e6f0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
e700: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
e710: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
e720: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
e730: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
e740: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
e750: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
e760: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
e770: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e780: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
e790: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
e7a0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
e7b0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
e7c0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
e7d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
e7e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
e7f0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
e800: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
e810: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
e820: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
e830: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e840: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
e850: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
e860: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
e870: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
e880: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
e890: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
e8a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
e8b0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
e8c0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
e8d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
e8e0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
e8f0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
e900: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
e910: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
e920: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
e930: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
e940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
e950: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
e960: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
e970: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
e980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
e990: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
e9a0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
e9b0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
e9c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9d0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
e9e0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
e9f0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
ea00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ea10: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
ea20: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
ea30: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
ea40: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
ea50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ea60: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
ea70: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
ea80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ea90: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
eaa0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
eab0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
eac0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ead0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
eae0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
eaf0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
eb00: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
eb10: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
eb20: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
eb30: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
eb40: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
eb50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
eb60: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
eb70: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
eb80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
eb90: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
eba0: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
ebb0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
ebc0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ebd0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
ebe0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
ebf0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
ec00: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
ec10: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
ec20: 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
ec30: 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
ec40: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
ec50: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
ec60: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 45 58 50  n Options.** EXP
ec70: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
ec80: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
ec90: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
eca0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
ecb0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
ecc0: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
ecd0: 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
ece0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
ecf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
ed00: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ed10: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
ed20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ed30: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
ed40: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
ed50: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
ed60: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
ed70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ed80: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
ed90: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
eda0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
edb0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
edc0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
edd0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ede0: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
edf0: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
ee00: 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
ee10: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ee20: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
ee30: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
ee40: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
ee50: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
ee60: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
ee70: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
ee80: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
ee90: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
eea0: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
eeb0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
eec0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
eed0: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
eee0: 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
eef0: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
ef00: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
ef10: 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
ef20: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
ef30: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
ef40: 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
ef50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ef60: 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
ef70: 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
ef80: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ef90: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
efa0: 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
efb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d  ointer to an mem
efc0: 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
efd0: 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
efe0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
eff0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
f000: 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
f010: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
f020: 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
f030: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
f040: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
f050: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
f060: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
f070: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
f080: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f090: 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
f0a0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
f0b0: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
f0c0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
f0d0: 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
f0e0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
f0f0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
f100: 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
f110: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
f120: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f130: 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
f140: 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
f150: 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
f160: 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
f170: 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
f180: 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
f190: 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
f1a0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
f1b0: 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
f1c0: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
f1d0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
f1e0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f1f0: 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
f200: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
f210: 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
f220: 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
f230: 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
f240: 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f  er.** multiple o
f250: 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20  f 8.  See also: 
f260: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
f270: 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a  OOKASIDE]</dd>.*
f280: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
f290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
f2a0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
f2b0: 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
f2c0: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f  * int int */.../
f2d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
f2e0: 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
f2f0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
f300: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
f310: 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
f320: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
f330: 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
f340: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
f350: 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
f360: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
f370: 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
f380: 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
f390: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
f3a0: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
f3b0: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
f3c0: 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
f3d0: 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
f3e0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
f3f0: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
f400: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
f410: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f420: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
f430: 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
f440: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
f450: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
f460: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
f470: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
f480: 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
f490: 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
f4a0: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
f4b0: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
f4c0: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
f4d0: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
f4e0: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
f4f0: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
f500: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
f510: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
f520: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
f530: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
f540: 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
f550: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
f560: 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
f570: 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
f580: 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
f590: 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
f5a0: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
f5b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
f5c0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
f5d0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
f5e0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
f5f0: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
f600: 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
f610: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
f620: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f630: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
f640: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
f650: 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
f660: 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
f670: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
f680: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
f690: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
f6a0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
f6b0: 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
f6c0: 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
f6d0: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
f6e0: 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64   then the [rowid
f6f0: 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
f700: 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
f710: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
f720: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
f730: 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
f740: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
f750: 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
f760: 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
f770: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
f780: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
f790: 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
f7a0: 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
f7b0: 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
f7c0: 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e  trigger fired.)^
f7d0: 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
f7e0: 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
f7f0: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
f800: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
f810: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
f820: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
f830: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
f840: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
f850: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
f860: 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
f870: 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
f880: 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
f890: 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
f8a0: 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
f8b0: 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
f8c0: 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
f8d0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f8e0: 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
f8f0: 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
f900: 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
f910: 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
f920: 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
f930: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
f940: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
f950: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
f960: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
f970: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
f980: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
f990: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
f9a0: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
f9b0: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
f9c0: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
f9d0: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
f9e0: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
f9f0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
fa00: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
fa10: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
fa20: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
fa30: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
fa40: 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
fa50: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
fa60: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
fa70: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
fa80: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
fa90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
faa0: 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
fab0: 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
fac0: 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
fad0: 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
fae0: 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
faf0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
fb00: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
fb10: 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
fb20: 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
fb30: 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
fb40: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
fb50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
fb60: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
fb70: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
fb80: 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
fb90: 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
fba0: 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
fbb0: 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
fbc0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
fbd0: 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
fbe0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
fbf0: 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
fc00: 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
fc10: 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
fc20: 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
fc30: 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
fc40: 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
fc50: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
fc60: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
fc70: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
fc80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fc90: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
fca0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
fcb0: 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
fcc0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
fcd0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
fce0: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
fcf0: 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
fd00: 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
fd10: 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
fd20: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
fd30: 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
fd40: 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
fd50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fd60: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
fd70: 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
fd80: 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
fd90: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
fda0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
fdb0: 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
fdc0: 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
fdd0: 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
fde0: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
fdf0: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
fe00: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
fe10: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
fe20: 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
fe30: 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
fe40: 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
fe50: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
fe60: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
fe70: 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
fe80: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
fe90: 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
fea0: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
feb0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
fec0: 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
fed0: 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
fee0: 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
fef0: 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
ff00: 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
ff10: 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
ff20: 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
ff30: 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
ff40: 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
ff50: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
ff60: 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
ff70: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
ff80: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
ff90: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
ffa0: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
ffb0: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
ffc0: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
ffd0: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
ffe0: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
fff0: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
10000 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
10010 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
10020 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
10030 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
10040 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
10050 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
10060 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
10070 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
10080 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
10090 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
100a0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
100b0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
100c0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
100d0 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
100e0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
100f0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
10100 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
10110 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
10120 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
10130 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
10140 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
10150 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
10160 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
10170 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
10180 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
10190 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
101a0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
101b0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
101c0 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
101d0 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
101e0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
101f0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
10200 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
10210 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
10220 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
10230 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
10240 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
10250 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
10260 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
10270 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
10280 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
10290 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
102a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
102b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
102c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
102d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
102e0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
102f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
10300 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
10310 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
10320 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
10330 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
10340 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
10350 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
10360 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
10370 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
10380 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
10390 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
103a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
103b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
103c0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
103d0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
103e0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
103f0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
10400 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
10410 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
10420 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
10430 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
10440 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
10450 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
10460 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
10470 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
10480 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
10490 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
104a0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
104b0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
104c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
104d0 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
104e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
104f0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
10500 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
10510 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
10520 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
10530 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
10540 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
10550 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10560 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
10570 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
10580 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
10590 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
105a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
105b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
105c0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
105d0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
105e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
105f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
10600 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
10610 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
10620 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
10630 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
10640 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
10650 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
10660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10670 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
10680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10690 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
106a0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
106b0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
106c0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
106d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
106e0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
106f0 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
10700 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
10710 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
10720 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
10730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10740 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
10750 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
10760 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
10770 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
10780 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
10790 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
107a0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
107b0 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
107c0 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
107d0 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
107e0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
107f0 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
10800 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
10810 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
10820 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
10830 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
10840 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
10850 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
10860 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
10870 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
10880 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
10890 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
108a0 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
108b0 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
108c0 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
108d0 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
108e0 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
108f0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
10900 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
10910 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
10920 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
10930 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
10940 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
10950 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
10960 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
10970 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
10980 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
10990 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
109a0 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
109b0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
109c0 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
109d0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
109e0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
109f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
10a00 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
10a10 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
10a20 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
10a30 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
10a40 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
10a50 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
10a60 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
10a70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
10a80 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
10a90 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
10aa0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
10ab0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
10ac0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
10ad0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
10ae0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
10af0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
10b00 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
10b10 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
10b20 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
10b30 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
10b40 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10b50 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
10b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
10b70 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
10b80 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
10b90 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
10ba0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
10bb0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
10bc0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
10bd0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
10be0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
10bf0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
10c00 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
10c10 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
10c20 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
10c30 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
10c40 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
10c50 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
10c60 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
10c70 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
10c80 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
10c90 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
10ca0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
10cb0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
10cc0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
10cd0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
10ce0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
10cf0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
10d00 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
10d10 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
10d20 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
10d30 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
10d40 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
10d50 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
10d60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10d70 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
10d80 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
10d90 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
10da0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
10db0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
10dc0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
10dd0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
10de0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
10df0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
10e00 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
10e10 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
10e20 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
10e30 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
10e40 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
10e50 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
10e60 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
10e70 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
10e80 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
10e90 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
10ea0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
10eb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
10ec0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
10ed0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
10ee0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10ef0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
10f00 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10f10 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
10f20 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
10f30 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
10f40 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
10f50 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
10f60 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
10f70 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
10f80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10f90 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
10fa0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
10fb0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
10fc0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
10fd0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
10fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10ff0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
11000 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
11010 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
11020 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
11030 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
11040 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
11050 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
11060 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
11070 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
11080 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
11090 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
110a0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
110b0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
110c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
110d0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
110e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
110f0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
11100 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
11110 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
11120 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
11130 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
11140 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
11150 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11160 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
11170 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11180 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
11190 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
111a0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
111b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
111c0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
111d0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
111e0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
111f0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
11200 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
11210 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
11220 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
11230 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
11240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
11250 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
11260 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
11270 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
11280 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
11290 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
112a0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
112b0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
112c0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
112d0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
112e0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
112f0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
11300 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
11310 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
11320 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
11330 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
11340 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
11350 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
11360 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
11370 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
11380 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
11390 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
113a0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
113b0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
113c0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
113d0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
113e0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
113f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
11400 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
11410 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
11420 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
11430 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
11440 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
11450 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
11460 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
11470 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
11480 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
11490 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
114a0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
114b0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
114c0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
114d0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
114e0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
114f0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
11500 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
11510 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
11520 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
11530 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
11540 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
11550 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
11560 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
11570 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
11580 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
11590 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
115a0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
115b0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
115c0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
115d0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
115e0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
115f0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
11600 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
11610 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
11620 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
11630 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
11640 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
11650 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11660 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
11670 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
11680 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
11690 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
116a0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
116b0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
116c0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
116d0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
116e0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
116f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
11700 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
11710 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
11720 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11730 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
11740 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
11750 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
11760 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
11770 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
11780 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
11790 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
117a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
117b0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
117c0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
117d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
117e0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
117f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
11800 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
11810 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
11820 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
11830 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
11840 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
11850 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
11860 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
11870 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
11880 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
11890 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
118a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
118b0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
118c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
118d0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
118e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
118f0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
11900 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
11910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
11920 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
11930 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
11940 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
11950 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
11960 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11970 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
11980 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
11990 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
119a0 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
119b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
119c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
119d0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
119e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
119f0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
11a00 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
11a10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
11a20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
11a30 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
11a40 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
11a50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
11a60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
11a70 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
11a80 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
11a90 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
11aa0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
11ab0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
11ac0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
11ad0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
11ae0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
11af0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
11b00 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
11b10 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
11b20 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
11b30 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
11b40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11b50 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
11b60 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
11b70 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
11b80 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
11b90 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
11ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
11bb0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
11bc0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11bd0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
11be0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
11bf0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
11c00 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
11c10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
11c20 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
11c30 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
11c40 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
11c50 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
11c60 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
11c70 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
11c80 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
11c90 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
11ca0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
11cb0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
11cc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
11cd0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
11ce0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
11cf0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
11d00 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
11d10 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
11d20 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
11d30 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
11d40 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
11d50 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
11d60 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
11d70 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
11d80 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
11d90 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
11da0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
11db0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
11dc0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
11dd0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
11de0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
11df0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
11e00 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
11e10 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
11e20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
11e30 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
11e40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11e50 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
11e60 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
11e70 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
11e80 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
11e90 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
11ea0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
11eb0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
11ec0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
11ed0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
11ee0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
11ef0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
11f00 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
11f10 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
11f20 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
11f30 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
11f40 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
11f50 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
11f60 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
11f70 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
11f80 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
11f90 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
11fa0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
11fb0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
11fc0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
11fd0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
11fe0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
11ff0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
12000 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
12010 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
12020 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
12030 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
12040 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
12050 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
12060 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
12070 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12080 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
12090 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
120a0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
120b0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
120c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
120d0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
120e0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
120f0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
12100 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
12110 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
12120 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
12130 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
12140 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
12150 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
12160 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
12170 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12180 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
12190 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
121a0 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
121b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
121c0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
121d0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
121e0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
121f0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
12200 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
12210 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
12220 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
12230 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
12240 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
12250 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
12260 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
12270 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
12280 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
12290 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
122a0 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
122b0 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
122c0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
122d0 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
122e0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
122f0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
12300 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
12310 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
12320 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
12330 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
12340 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
12350 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
12360 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
12370 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
12380 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
12390 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
123a0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
123b0 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
123c0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
123d0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
123e0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
123f0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
12400 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
12410 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
12420 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
12430 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
12440 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
12450 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
12460 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
12470 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
12480 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
12490 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
124a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
124b0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
124c0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
124d0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
124e0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
124f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
12500 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
12510 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
12520 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
12530 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
12540 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
12550 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
12560 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
12570 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
12580 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
12590 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
125a0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
125b0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
125c0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
125d0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
125e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
125f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
12600 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
12610 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
12620 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
12630 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
12640 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
12650 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
12660 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
12670 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
12680 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
12690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
126a0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
126b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
126c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
126d0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
126e0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
126f0 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
12700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12710 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
12720 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
12730 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
12740 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
12750 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
12760 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
12770 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
12780 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
12790 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
127a0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
127b0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
127c0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
127d0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
127e0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
127f0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
12800 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
12810 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
12820 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
12830 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
12840 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
12850 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
12860 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
12870 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
12880 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
12890 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
128a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
128b0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
128c0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
128d0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
128e0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
128f0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
12900 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
12910 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
12920 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
12930 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
12940 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
12950 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
12960 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12970 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
12980 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
12990 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
129a0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
129b0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
129c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
129d0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
129e0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
129f0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
12a00 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
12a10 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
12a20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12a30 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
12a40 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
12a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12a60 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
12a70 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
12a80 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
12a90 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
12aa0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
12ab0 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
12ac0 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
12ad0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
12ae0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12af0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
12b00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
12b10 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
12b20 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
12b30 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
12b40 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
12b50 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
12b60 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
12b70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
12b80 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
12b90 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
12ba0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
12bb0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
12bc0 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
12bd0 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
12be0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
12bf0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
12c00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
12c10 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
12c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
12c30 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
12c40 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
12c50 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
12c60 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
12c70 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
12c80 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
12c90 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
12ca0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
12cb0 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
12cc0 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
12cd0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
12ce0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
12cf0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
12d00 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
12d10 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
12d20 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
12d30 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
12d40 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
12d50 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
12d60 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
12d70 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
12d80 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
12d90 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
12da0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
12db0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
12dc0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
12dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
12de0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
12df0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
12e00 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
12e10 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
12e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
12e30 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
12e40 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
12e50 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
12e60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
12e70 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
12e80 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
12e90 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
12ea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
12eb0 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
12ec0 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
12ed0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
12ee0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
12ef0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
12f00 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
12f10 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
12f20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
12f30 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
12f40 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
12f50 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
12f60 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
12f70 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
12f80 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
12f90 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
12fa0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
12fb0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
12fc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12fd0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
12fe0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
12ff0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
13000 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
13010 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
13020 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
13030 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
13040 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
13050 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
13060 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
13070 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
13080 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
13090 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
130a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
130b0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
130c0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
130d0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
130e0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
130f0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
13100 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13110 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
13120 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13130 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
13140 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13150 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
13160 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13170 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
13180 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
13190 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
131a0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
131b0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
131c0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
131d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
131e0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e>.**.** ^The sq
131f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13200 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
13210 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
13220 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
13230 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
13240 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
13250 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
13260 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
13270 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
13280 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
13290 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
132a0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
132b0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
132c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
132d0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
132e0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
132f0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
13300 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
13310 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
13320 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73  * it should pass
13330 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13340 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
13350 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
13360 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
13370 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
13380 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
13390 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
133a0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
133b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
133c0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
133d0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
133e0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
133f0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
13400 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
13410 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
13420 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
13430 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
13440 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
13450 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
13460 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
13470 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
13480 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
13490 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
134a0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
134b0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
134c0 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
134d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
134e0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
134f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
13500 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
13510 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
13520 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
13530 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
13540 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
13550 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
13560 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
13570 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
13580 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
13590 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
135a0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
135b0 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
135c0 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
135d0 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
135e0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
135f0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
13600 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
13610 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
13620 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
13630 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
13640 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ].)^.*/.int sqli
13650 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
13660 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
13670 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
13680 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
13690 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
136a0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
136b0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
136c0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
136d0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
136e0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
136f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
13700 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
13710 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
13720 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
13730 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
13740 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
13750 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
13760 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
13770 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
13780 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
13790 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
137a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
137b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
137c0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
137d0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
137e0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
137f0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
13800 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
13810 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13820 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
13830 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
13840 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
13850 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
13860 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
13870 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
13880 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
13890 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
138a0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
138b0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
138c0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
138d0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
138e0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
138f0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
13900 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
13910 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
13920 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
13930 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
13940 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
13950 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
13960 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
13970 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
13980 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13990 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
139a0 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
139b0 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
139c0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
139d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  tring..**.** ^(I
139e0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
139f0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
13a00 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
13a10 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
13a20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
13a30 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
13a40 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
13a50 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
13a60 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
13a70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13a80 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
13a90 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
13aa0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13ab0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
13ac0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
13ad0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
13ae0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
13af0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
13b00 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
13b10 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
13b20 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
13b30 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
13b40 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
13b50 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
13b60 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
13b70 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
13b80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
13b90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
13ba0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
13bb0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
13bc0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
13bd0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
13be0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
13bf0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
13c00 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
13c10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
13c20 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
13c30 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
13c40 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
13c50 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
13c60 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
13c70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
13c80 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
13c90 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
13ca0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
13cb0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
13cc0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
13cd0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
13ce0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
13cf0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
13d00 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
13d10 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
13d20 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
13d30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
13d40 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
13d50 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
13d60 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
13d70 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
13d80 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
13d90 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
13da0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
13db0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
13dc0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
13dd0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
13de0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
13df0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
13e00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
13e10 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
13e20 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
13e30 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
13e40 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
13e50 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
13e60 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
13e70 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
13e80 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
13e90 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
13ea0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
13eb0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
13ec0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
13ed0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
13ee0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
13ef0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
13f00 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
13f10 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
13f20 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
13f30 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
13f40 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
13f50 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
13f60 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
13f70 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
13f80 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
13f90 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
13fa0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
13fb0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
13fc0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
13fd0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
13fe0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
13ff0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
14000 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
14010 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
14020 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
14030 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
14040 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
14050 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
14060 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
14070 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
14080 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
14090 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
140a0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
140b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
140c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
140d0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
140e0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
140f0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
14100 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14110 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14120 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
14130 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
14140 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
14150 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
14160 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
14170 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
14180 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
14190 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
141a0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
141b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
141c0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
141d0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
141e0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
141f0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
14200 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
14210 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
14220 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
14230 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
14240 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14250 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
14260 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
14270 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
14280 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
14290 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
142a0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
142b0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
142c0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
142d0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
142e0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
142f0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
14300 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
14310 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
14320 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
14330 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
14340 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
14350 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14360 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
14370 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
14380 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
14390 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
143a0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
143b0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
143c0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
143d0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
143e0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
143f0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
14400 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
14410 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
14420 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
14430 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
14440 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
14450 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
14460 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
14470 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
14480 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
14490 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
144a0 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
144b0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
144c0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
144d0 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
144e0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
144f0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
14500 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
14510 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
14520 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
14530 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
14540 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
14550 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
14560 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
14570 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
14580 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
14590 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
145a0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
145b0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
145c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
145d0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
145e0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
145f0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
14600 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
14610 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
14620 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
14630 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
14640 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
14650 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
14660 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
14670 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
14680 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
14690 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
146a0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
146b0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
146c0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
146d0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
146e0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
146f0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
14700 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
14710 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
14720 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
14730 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
14740 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
14750 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
14760 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
14770 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
14780 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
14790 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
147a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
147b0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
147c0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
147d0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
147e0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
147f0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
14800 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
14810 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
14820 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
14830 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
14840 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
14850 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
14860 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
14870 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
14880 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
14890 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
148a0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
148b0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
148c0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
148d0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
148e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
148f0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
14900 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14910 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
14920 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
14930 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
14940 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
14950 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
14960 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
14970 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
14980 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
14990 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
149a0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
149b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
149c0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
149d0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
149e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
149f0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
14a00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
14a10 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
14a20 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
14a30 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
14a40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
14a50 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
14a60 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
14a70 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
14a80 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
14a90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
14aa0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
14ab0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
14ac0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
14ad0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
14ae0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
14af0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
14b00 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
14b10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
14b20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
14b30 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
14b40 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
14b50 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
14b60 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
14b70 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
14b80 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
14b90 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
14ba0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
14bb0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
14bc0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
14bd0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
14be0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
14bf0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
14c00 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
14c10 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
14c20 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
14c30 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
14c40 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
14c50 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
14c60 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
14c70 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
14c80 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
14c90 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
14ca0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
14cb0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
14cc0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
14cd0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
14ce0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
14cf0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
14d00 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
14d10 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
14d20 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
14d30 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
14d40 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
14d50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
14d60 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
14d70 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
14d80 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
14d90 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
14da0 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
14db0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14dc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
14dd0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
14de0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
14df0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
14e00 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
14e10 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
14e20 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
14e30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14e40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
14e50 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
14e60 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14e70 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
14e80 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
14e90 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
14ea0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
14eb0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
14ec0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
14ed0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
14ee0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
14ef0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14f00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14f10 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
14f20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14f30 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14f40 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
14f50 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
14f60 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
14f70 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
14f80 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
14f90 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
14fa0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
14fb0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
14fc0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
14fd0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
14fe0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
14ff0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
15000 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
15010 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
15020 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
15030 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
15040 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
15050 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
15060 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
15070 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
15080 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
15090 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
150a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
150b0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
150c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
150d0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
150e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
150f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
15100 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
15110 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
15120 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
15130 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a   boundary..**.**
15140 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
15150 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
15160 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
15170 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
15180 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
15190 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
151a0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
151b0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
151c0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
151d0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
151e0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
151f0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
15200 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
15210 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
15220 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
15230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
15240 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
15250 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
15260 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
15270 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
15280 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
15290 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
152a0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
152b0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
152c0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
152d0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
152e0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
152f0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
15300 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
15310 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
15320 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
15330 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
15340 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
15350 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
15360 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
15370 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
15380 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
15390 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
153a0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
153b0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
153c0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
153d0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
153e0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
153f0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
15400 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15410 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
15420 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
15430 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
15440 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
15450 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
15460 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
15470 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
15480 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
15490 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
154a0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
154b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
154c0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
154d0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
154e0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
154f0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
15500 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
15510 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
15520 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
15530 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15540 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
15550 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
15560 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
15570 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15580 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
15590 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
155a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
155b0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
155c0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
155d0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
155e0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
155f0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
15600 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
15610 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
15620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
15630 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
15640 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
15650 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15660 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
15670 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
15680 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
15690 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
156a0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
156b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
156c0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
156d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
156e0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
156f0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
15700 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
15710 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
15720 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
15730 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15740 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
15750 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
15760 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
15770 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
15780 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
15790 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
157a0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
157b0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
157c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
157d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
157e0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
157f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
15800 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15810 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
15820 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
15830 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
15840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15850 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15860 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
15870 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
15880 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
15890 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
158a0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
158b0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
158c0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
158d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
158e0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
158f0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
15900 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
15910 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
15920 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
15930 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
15940 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
15950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
15960 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15970 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
15980 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
15990 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
159a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
159b0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
159c0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
159d0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
159e0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
159f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
15a00 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
15a10 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
15a20 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15a30 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
15a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15a50 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
15a60 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
15a70 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
15a80 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
15a90 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
15aa0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
15ab0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
15ac0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
15ad0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
15ae0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
15af0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
15b00 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
15b10 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
15b20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
15b30 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
15b40 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
15b50 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
15b60 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
15b70 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
15b80 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
15b90 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
15ba0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
15bb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
15bc0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
15bd0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
15be0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
15bf0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
15c00 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
15c10 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
15c20 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
15c30 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
15c40 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
15c50 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
15c60 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
15c70 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
15c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
15c90 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
15ca0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
15cb0 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
15cc0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
15cd0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
15ce0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
15cf0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
15d00 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
15d10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
15d20 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
15d30 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
15d40 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
15d50 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
15d60 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
15d70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
15d80 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
15d90 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
15da0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
15db0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
15dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15dd0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
15de0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
15df0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
15e00 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
15e10 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
15e20 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
15e30 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
15e40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15e50 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
15e60 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15e70 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
15e80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15e90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
15ea0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15eb0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
15ec0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
15ed0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
15ee0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
15ef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
15f00 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
15f10 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
15f20 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
15f30 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
15f40 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
15f50 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
15f60 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
15f70 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
15f80 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
15f90 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
15fa0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
15fb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15fc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
15fd0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
15fe0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
15ff0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
16000 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16010 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
16020 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
16030 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
16040 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
16050 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
16060 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
16070 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
16080 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
16090 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
160a0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
160b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
160c0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
160d0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
160e0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
160f0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
16100 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
16110 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16120 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
16130 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
16140 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
16150 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
16160 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16170 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
16180 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16190 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
161a0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
161b0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
161c0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
161d0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
161e0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
161f0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
16200 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16210 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
16220 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
16230 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
16240 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
16250 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
16260 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
16270 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
16280 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
16290 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
162a0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
162b0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
162c0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
162d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
162e0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
162f0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
16300 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
16310 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16320 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16330 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
16340 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
16350 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
16360 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
16370 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
16380 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
16390 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
163a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
163b0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
163c0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
163d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
163e0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
163f0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
16400 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
16410 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
16420 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
16430 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
16440 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
16450 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
16460 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
16470 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
16480 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
16490 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
164a0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
164b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
164c0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
164d0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
164e0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
164f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
16500 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
16510 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
16520 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
16530 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
16540 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
16550 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
16560 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
16570 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
16580 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
16590 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
165a0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
165b0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
165c0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
165d0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
165e0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
165f0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
16600 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
16610 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
16620 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
16630 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
16640 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
16650 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
16660 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
16670 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
16680 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
16690 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
166a0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
166b0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
166c0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
166d0 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
166e0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
166f0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
16700 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
16710 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
16720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
16730 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
16740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
16750 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
16760 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
16770 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
16780 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
16790 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
167a0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
167b0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
167c0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
167d0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
167e0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
167f0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
16800 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
16810 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
16820 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
16830 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
16840 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
16850 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
16860 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
16870 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
16880 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
16890 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
168a0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
168b0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
168c0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
168d0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
168e0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
168f0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
16900 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
16910 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
16920 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
16930 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
16940 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
16950 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
16960 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
16970 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
16980 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
16990 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
169a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
169b0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
169c0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
169d0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
169e0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
169f0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
16a00 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
16a10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
16a20 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
16a30 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
16a40 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
16a50 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
16a60 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
16a70 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
16a80 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
16a90 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
16aa0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
16ab0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
16ac0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
16ad0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
16ae0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
16af0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
16b00 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
16b10 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
16b20 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
16b30 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
16b40 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
16b50 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
16b60 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
16b70 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
16b80 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
16b90 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
16ba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
16bb0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
16bc0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
16bd0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
16be0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
16bf0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
16c00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16c10 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
16c20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16c30 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
16c40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
16c50 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
16c60 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16c70 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
16c80 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
16c90 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
16ca0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
16cb0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
16cc0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
16cd0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
16ce0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
16cf0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
16d00 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
16d10 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
16d20 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
16d30 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
16d40 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
16d50 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
16d60 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
16d70 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
16d80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16d90 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
16da0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
16db0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
16dc0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
16dd0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16de0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16df0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
16e00 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
16e10 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
16e20 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
16e30 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
16e40 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
16e50 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
16e60 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
16e70 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
16e80 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
16e90 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
16ea0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
16eb0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
16ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
16ed0 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
16ee0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
16ef0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
16f00 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
16f10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
16f20 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
16f30 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
16f40 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
16f50 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
16f60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16f70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
16f80 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
16f90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
16fa0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
16fb0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
16fc0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
16fd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
16fe0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16ff0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
17000 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
17010 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
17020 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
17030 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
17040 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
17050 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
17060 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
17070 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
17080 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
17090 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
170a0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
170b0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
170c0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
170d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
170e0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
170f0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
17100 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
17110 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
17120 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
17130 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
17140 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
17150 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
17160 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
17170 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
17180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
17190 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
171a0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
171b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
171c0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
171d0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
171e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
171f0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
17200 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
17210 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
17220 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
17230 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
17240 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17250 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
17260 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
17270 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
17280 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
17290 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
172a0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
172b0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
172c0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
172d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
172e0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
172f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
17300 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
17310 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
17320 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
17330 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
17340 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
17350 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
17360 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
17370 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
17380 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
17390 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
173a0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
173b0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
173c0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
173d0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
173e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
173f0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
17400 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
17410 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17420 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
17430 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
17440 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
17450 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
17460 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
17470 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
17480 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17490 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
174a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
174b0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
174c0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
174d0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
174e0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
174f0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
17500 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
17510 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
17520 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
17530 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
17540 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
17550 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17560 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
17570 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
17580 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
17590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
175a0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
175b0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
175c0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
175d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
175e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
175f0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
17600 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
17610 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17620 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17640 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
17650 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
17660 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17670 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17690 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
176a0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
176b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
176c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
176d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
176e0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
176f0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
17700 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
17710 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
17720 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17730 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
17740 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
17750 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
17760 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17770 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17780 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
17790 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
177a0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
177b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
177c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
177d0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
177e0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
177f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17810 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
17820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
17830 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17860 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
17870 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
17880 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
17890 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
178a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
178b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
178c0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
178d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
178e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
178f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17900 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
17910 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
17920 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17930 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17950 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
17960 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
17970 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17980 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
179a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
179b0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
179c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
179d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
179e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
179f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
17a00 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
17a10 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
17a20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a40 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
17a50 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
17a60 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
17a70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a90 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
17aa0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
17ab0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
17ac0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
17ae0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
17af0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
17b00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17b10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
17b30 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
17b40 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
17b50 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
17b60 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
17b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
17b80 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
17b90 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
17ba0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
17bb0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
17bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
17bd0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
17be0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
17bf0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
17c00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17c10 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
17c20 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
17c30 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
17c40 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
17c50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17c60 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
17c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
17c80 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
17c90 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
17ca0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17cb0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
17cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
17cd0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
17ce0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17cf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17d00 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
17d10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
17d20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
17d30 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
17d40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17d50 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
17d60 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
17d70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
17d80 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
17d90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17da0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
17db0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
17dc0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
17dd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17df0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
17e00 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
17e10 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17e20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17e40 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
17e50 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
17e60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17e70 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
17e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17e90 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
17ea0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
17eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17ec0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
17ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ee0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
17ef0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
17f00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
17f10 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
17f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17f30 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
17f40 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
17f50 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
17f60 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
17f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f80 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
17f90 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
17fa0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
17fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17fc0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
17fd0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
17fe0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
17ff0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
18000 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
18010 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
18020 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
18030 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
18040 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
18050 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
18060 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18070 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
18080 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
18090 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
180a0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
180b0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
180c0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
180d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
180e0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
180f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18100 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
18110 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
18120 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
18130 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
18140 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
18150 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
18160 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
18170 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
18180 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
18190 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
181a0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
181b0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
181c0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
181d0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
181e0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
181f0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
18200 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
18210 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
18220 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
18230 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
18240 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
18250 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
18260 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18270 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
18280 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18290 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
182a0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
182b0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
182c0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
182d0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
182e0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
182f0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
18300 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
18310 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
18320 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
18330 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
18340 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
18350 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
18360 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
18370 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
18380 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
18390 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
183a0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
183b0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
183c0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
183d0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
183e0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
183f0 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
18400 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
18410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18420 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
18430 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
18440 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f  ^This routine co
18450 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
18460 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
18470 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
18480 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
18490 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
184a0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
184b0 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
184c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
184d0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
184e0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
184f0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
18500 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
18510 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
18520 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
18530 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
18540 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
18550 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
18560 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
18570 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
18580 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
18590 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
185a0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
185b0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
185c0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
185d0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
185e0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
185f0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
18600 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
18610 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
18620 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f  dler must not do
18630 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
18640 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
18650 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18660 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
18670 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
18680 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
18690 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
186a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
186b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
186c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
186d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
186e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
186f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
18700 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
18710 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
18720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
18730 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
18740 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
18750 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
18760 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
18770 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
18780 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
18790 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
187a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
187b0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
187c0 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
187d0 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
187e0 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
187f0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
18800 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
18810 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
18820 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
18830 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
18840 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
18850 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
18860 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
18870 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
18880 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
18890 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
188a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
188b0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
188c0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
188d0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
188e0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
188f0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
18900 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
18910 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
18920 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
18930 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
18940 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
18950 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
18960 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
18970 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
18980 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
18990 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
189a0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
189b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
189c0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
189d0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
189e0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
189f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
18a00 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
18a10 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
18a20 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
18a30 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
18a40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
18a50 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
18a60 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
18a70 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
18a80 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
18a90 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
18aa0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
18ab0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
18ac0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
18ad0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
18ae0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
18af0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
18b00 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
18b10 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
18b20 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
18b30 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
18b40 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
18b50 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
18b60 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
18b70 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
18b80 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
18b90 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
18ba0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
18bb0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
18bc0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
18bd0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
18be0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
18bf0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
18c00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18c10 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
18c20 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
18c30 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
18c40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
18c50 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
18c60 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
18c70 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
18c80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
18c90 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
18ca0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
18cb0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
18cc0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
18cd0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
18ce0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
18cf0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
18d00 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
18d10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18d20 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
18d30 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
18d40 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
18d50 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
18d60 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
18d70 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
18d80 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
18d90 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
18da0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
18db0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
18dc0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
18dd0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
18de0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
18df0 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  * and/or [SQLITE
18e00 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
18e10 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  HE] flags:)^.**.
18e20 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
18e30 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
18e40 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
18e50 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
18e60 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
18e70 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
18e80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
18e90 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
18ea0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
18eb0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
18ec0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
18ed0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
18ee0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
18ef0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18f00 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
18f10 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
18f20 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
18f30 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
18f40 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
18f50 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
18f60 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
18f70 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
18f80 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
18f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
18fa0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
18fb0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
18fc0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
18fd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
18fe0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
18ff0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
19000 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
19010 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
19020 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
19030 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
19040 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
19050 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
19060 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
19070 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
19080 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
19090 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
190a0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
190b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
190c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
190d0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
190e0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
190f0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
19100 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
19110 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
19120 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
19130 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
19140 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
19150 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
19160 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
19170 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
19180 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
19190 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
191a0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
191b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
191c0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
191d0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
191e0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
191f0 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
19200 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
19210 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
19220 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
19230 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
19240 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
19250 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19260 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
19270 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
19280 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
19290 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
192a0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
192b0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
192c0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
192d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
192e0 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
192f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
19300 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
19310 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
19320 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19330 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
19340 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
19350 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
19360 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
19370 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
19380 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
19390 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
193a0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
193b0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
193c0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
193d0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
193e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
193f0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
19400 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
19410 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
19420 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
19430 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
19440 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
19450 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
19460 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
19470 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
19480 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
19490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
194a0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
194b0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
194c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
194d0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
194e0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
194f0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
19500 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
19510 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
19520 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
19530 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
19540 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
19550 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
19560 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
19570 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
19580 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
19590 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
195a0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
195b0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
195c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
195d0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
195e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
195f0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
19600 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
19610 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
19620 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
19630 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
19640 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
19650 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
19660 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
19670 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
19680 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
19690 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
196a0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
196b0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
196c0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
196d0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
196e0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
196f0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
19700 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
19710 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
19720 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
19730 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
19740 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
19750 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
19760 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
19770 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
19780 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
19790 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
197a0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
197b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
197c0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
197d0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
197e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
197f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
19800 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
19810 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
19820 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
19830 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
19840 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
19850 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
19860 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
19870 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
19880 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
19890 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
198a0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
198b0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
198c0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
198d0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
198e0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
198f0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
19900 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
19910 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
19920 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19930 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
19940 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19950 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
19960 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
19970 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
19980 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
19990 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
199a0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
199b0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
199c0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
199d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
199e0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
199f0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
19a00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
19a10 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
19a20 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
19a30 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
19a40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
19a50 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
19a60 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
19a70 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
19a80 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
19a90 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
19aa0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
19ab0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
19ac0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
19ad0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
19ae0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
19af0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
19b00 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
19b10 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
19b20 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
19b30 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
19b40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
19b50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
19b60 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
19b70 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
19b80 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
19b90 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
19ba0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
19bb0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
19bc0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
19bd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
19be0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
19bf0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
19c00 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
19c10 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
19c20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19c30 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
19c40 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
19c50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19c60 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
19c70 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
19c80 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
19c90 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
19ca0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
19cb0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
19cc0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
19cd0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
19ce0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
19cf0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
19d00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
19d10 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
19d20 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
19d30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
19d40 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
19d50 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
19d60 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
19d70 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
19d80 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
19d90 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19da0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
19db0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
19dc0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
19dd0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
19de0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
19df0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
19e00 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
19e10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
19e20 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
19e30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
19e40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
19e50 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
19e60 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
19e70 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
19e80 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
19e90 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
19ea0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
19eb0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
19ec0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
19ed0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
19ee0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
19ef0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
19f00 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
19f10 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
19f20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
19f30 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
19f40 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
19f50 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
19f60 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
19f70 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
19f80 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
19f90 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
19fa0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
19fb0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
19fc0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
19fd0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
19fe0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
19ff0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1a000 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1a010 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1a020 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1a030 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1a040 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1a050 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1a060 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1a070 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1a080 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1a090 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1a0a0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1a0b0 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1a0c0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1a0d0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1a0e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1a0f0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1a100 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1a110 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1a120 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1a130 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1a140 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1a150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a160 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1a170 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1a180 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1a190 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1a1a0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1a1b0 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1a1c0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1a1d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1a1e0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1a1f0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1a200 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1a210 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1a220 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1a230 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1a240 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1a250 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1a260 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1a270 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1a280 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1a290 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1a2a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1a2b0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1a2c0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1a2d0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1a2e0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1a2f0 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
1a300 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1a310 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
1a320 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1a330 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
1a340 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1a350 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1a360 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1a370 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1a380 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1a390 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a3a0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1a3b0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
1a3c0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1a3d0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1a3e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a3f0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1a400 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1a410 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1a420 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1a430 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1a440 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1a450 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1a460 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a470 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1a480 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1a490 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1a4a0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1a4b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1a4c0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1a4d0 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1a4e0 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1a4f0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1a500 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1a510 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1a520 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a530 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1a540 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1a550 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1a560 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1a570 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1a580 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1a590 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1a5a0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1a5b0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1a5c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1a5d0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1a5e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1a5f0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1a600 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1a610 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1a620 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1a630 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1a640 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1a650 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1a660 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1a670 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1a680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1a690 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1a6a0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1a6b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1a6c0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1a6d0 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1a6e0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1a6f0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1a700 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1a710 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1a720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a730 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1a740 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
1a750 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1a760 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1a770 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1a780 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1a790 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1a7a0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1a7b0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1a7c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1a7d0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1a7e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1a7f0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1a800 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1a810 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1a820 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1a830 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1a840 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1a850 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1a860 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1a870 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1a880 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1a890 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1a8a0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1a8b0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1a8c0 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1a8d0 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1a8e0 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  mit.)^.**.** ^If
1a8f0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1a900 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1a910 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1a920 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1a930 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  ^(For the limit 
1a940 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1a950 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1a960 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
1a970 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
1a980 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
1a990 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
1a9a0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1a9b0 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
1a9c0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1a9d0 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
1a9e0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1a9f0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1aa00 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1aa10 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1aa20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1aa30 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1aa40 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1aa50 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1aa60 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1aa70 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1aa80 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
1aa90 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
1aaa0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
1aab0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
1aac0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
1aad0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
1aae0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
1aaf0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
1ab00 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
1ab10 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
1ab20 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
1ab30 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
1ab40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1ab50 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
1ab60 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
1ab70 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
1ab80 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
1ab90 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
1aba0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
1abb0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
1abc0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
1abd0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
1abe0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
1abf0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
1ac00 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
1ac10 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
1ac20 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
1ac30 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
1ac40 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
1ac50 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1ac60 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
1ac70 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
1ac80 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
1ac90 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
1aca0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
1acb0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
1acc0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
1acd0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
1ace0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1acf0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
1ad00 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
1ad10 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
1ad20 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
1ad30 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
1ad40 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
1ad50 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
1ad60 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
1ad70 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
1ad80 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
1ad90 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
1ada0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
1adb0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
1adc0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
1add0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1ade0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1adf0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
1ae00 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
1ae10 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
1ae20 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1ae30 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
1ae40 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1ae50 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1ae60 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
1ae70 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1ae80 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1ae90 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
1aea0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
1aeb0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
1aec0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
1aed0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1aee0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
1aef0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
1af00 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1af10 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1af20 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1af30 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1af40 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1af50 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1af60 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1af70 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1af80 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1af90 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1afa0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1afb0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1afc0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
1afd0 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
1afe0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1aff0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1b000 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1b010 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1b020 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1b030 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1b040 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1b050 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b060 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1b070 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b080 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1b090 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1b0a0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1b0b0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1b0c0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1b0d0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1b0e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1b0f0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1b100 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1b110 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1b120 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1b130 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1b140 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1b150 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1b160 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1b170 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1b180 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1b190 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1b1a0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1b1b0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1b1c0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1b1d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b1e0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1b1f0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1b200 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1b210 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b220 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1b230 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1b240 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b250 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1b260 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1b270 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1b280 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1b290 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1b2a0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1b2b0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1b2c0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1b2d0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
1b2e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b2f0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1b300 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
1b310 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1b320 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1b330 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1b340 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1b350 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
1b360 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
1b370 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
1b380 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  d>.**.** ^(<dt>S
1b390 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1b3a0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1b3b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b3c0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1b3d0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1b3e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
1b3f0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
1b400 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
1b410 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1b430 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1b440 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b450 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1b460 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1b470 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1b480 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1b490 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1b4a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1b4b0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1b4c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b4d0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1b4e0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1b4f0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1b500 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1b510 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1b520 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1b530 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1b540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1b550 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1b560 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1b570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1b580 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1b590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1b5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1b5b0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1b5c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1b5d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b5e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1b5f0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1b600 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1b610 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1b620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b630 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1b640 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1b650 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1b660 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1b670 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1b680 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1b690 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1b6a0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1b6b0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1b6c0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1b6d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1b6e0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1b6f0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1b700 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1b710 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1b720 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1b730 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1b740 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1b750 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1b760 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1b770 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1b780 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1b790 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1b7a0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1b7b0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1b7c0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1b7d0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1b7e0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1b7f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1b800 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1b810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b820 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1b830 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1b840 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1b850 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1b860 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b870 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1b880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1b890 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1b8a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1b8b0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1b8c0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1b8d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1b8e0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1b8f0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1b900 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1b910 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1b920 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1b930 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1b940 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1b950 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b960 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1b970 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1b980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1b990 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1b9a0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1b9b0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1b9c0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1b9d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1b9e0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1b9f0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1ba00 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1ba10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1ba20 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1ba30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1ba40 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1ba50 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1ba60 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1ba70 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1ba80 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1ba90 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1baa0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1bab0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1bac0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1bad0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1bae0 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1baf0 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1bb00 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1bb10 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1bb20 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1bb30 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1bb40 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1bb50 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1bb60 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1bb70 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1bb80 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1bb90 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1bba0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1bbb0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1bbc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1bbd0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1bbe0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1bbf0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1bc00 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1bc10 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1bc20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1bc30 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1bc40 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1bc50 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1bc60 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1bc70 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1bc80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1bc90 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1bca0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1bcb0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1bcc0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1bcd0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1bce0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1bcf0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1bd00 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1bd10 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1bd20 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1bd30 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1bd40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1bd50 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1bd60 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1bd70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bd80 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1bd90 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1bda0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1bdb0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1bdc0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1bdd0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1bde0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1bdf0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1be00 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1be10 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1be20 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1be30 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1be40 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1be50 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1be60 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1be70 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1be80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1be90 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1bea0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1beb0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1bec0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1bed0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1bee0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1bef0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1bf00 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1bf10 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1bf20 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1bf30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1bf40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1bf50 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1bf60 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1bf70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1bf80 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1bf90 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1bfa0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1bfb0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1bfc0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1bfd0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1bfe0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1bff0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1c000 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1c010 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1c020 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1c030 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1c040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1c050 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1c060 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1c070 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1c080 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1c090 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1c0a0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1c0b0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1c0c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1c0d0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1c0e0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1c0f0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1c100 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1c110 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1c120 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1c130 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1c140 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1c150 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1c160 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1c170 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1c180 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1c190 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1c1a0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1c1b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1c1c0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1c1d0 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 68 65  n.  ^If the sche
1c1e0 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1c1f0 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1c200 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1c210 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1c220 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1c230 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1c240 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1c250 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1c260 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1c270 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1c280 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1c290 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1c2a0 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1c2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c2c0 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1c2d0 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1c2e0 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1c2f0 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1c300 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1c310 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1c320 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1c330 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1c340 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1c350 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1c360 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1c370 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1c380 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1c390 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c3a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1c3b0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1c3c0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1c3d0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1c3e0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1c3f0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1c400 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1c410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c420 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1c430 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1c440 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1c450 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1c460 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1c470 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1c480 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1c490 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1c4a0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1c4b0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1c4c0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1c4d0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1c4e0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1c4f0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1c500 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1c510 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1c520 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1c530 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1c540 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1c550 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  i>.** ^If the va
1c560 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65  lue of a [parame
1c570 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
1c580 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45  eter] in the WHE
1c590 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a  RE clause might.
1c5a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71 75  ** change the qu
1c5b0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
1c5c0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74  tatement, then t
1c5d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  he statement may
1c5e0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1c5f0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20  ally recompiled 
1c600 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64  (as if there had
1c610 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63   been a schema c
1c620 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69  hange) on the fi
1c630 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rst .** [sqlite3
1c640 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
1c650 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
1c660 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  ge to the .** [s
1c670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c680 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1c690 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  the [parameter].
1c6a0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
1c6b0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
1c6c0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1c6d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1c6e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1c6f0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1c700 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1c710 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1c720 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1c730 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1c740 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1c750 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1c760 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1c770 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1c780 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1c790 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1c7a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1c7b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1c7c0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1c7d0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1c7e0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1c7f0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1c800 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c810 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1c820 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1c830 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1c840 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1c850 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1c860 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1c870 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1c880 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1c890 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1c8a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1c8b0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1c8c0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1c8d0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1c8e0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1c8f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1c900 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1c910 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1c920 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1c930 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1c940 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1c950 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1c960 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1c970 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1c980 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1c990 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1c9a0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1c9b0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1c9c0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1c9d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1c9e0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1c9f0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ca00 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ca10 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1ca20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ca30 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1ca40 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1ca50 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1ca60 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1ca70 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1ca80 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1ca90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1caa0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1cab0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1cac0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1cad0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1cae0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1caf0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1cb00 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1cb10 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1cb20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1cb30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1cb40 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1cb50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1cb60 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1cb70 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1cb80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1cb90 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1cba0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1cbb0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1cbc0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1cbd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cbe0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1cbf0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
1cc00 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1cc10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1cc20 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1cc30 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1cc40 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1cc50 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1cc60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1cc70 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1cc80 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1cc90 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1cca0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1ccb0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1ccc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ccd0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
1cce0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1ccf0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1cd00 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1cd10 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
1cd20 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1cd30 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
1cd40 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1cd50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1cd60 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1cd70 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1cd80 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1cd90 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1cda0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1cdb0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1cdc0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1cdd0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1cde0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1cdf0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1ce00 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1ce10 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1ce20 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
1ce30 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
1ce40 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
1ce50 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
1ce60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1ce70 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1ce80 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1ce90 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1cea0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1ceb0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1cec0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1ced0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1cee0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1cef0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1cf00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1cf10 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1cf20 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1cf30 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1cf40 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1cf50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1cf60 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1cf70 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1cf80 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1cf90 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1cfa0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
1cfb0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
1cfc0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
1cfd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1cfe0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
1cff0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
1d000 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
1d010 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
1d020 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
1d030 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
1d040 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
1d050 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
1d060 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d070 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
1d080 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
1d090 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
1d0a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d0b0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
1d0c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1d0d0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
1d0e0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
1d0f0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
1d100 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
1d110 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1d120 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1d130 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
1d140 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
1d150 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
1d160 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
1d170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
1d180 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
1d190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1d1a0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
1d1b0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
1d1c0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1d1d0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1d1e0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1d1f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d200 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
1d210 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
1d220 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
1d230 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
1d240 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
1d250 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
1d260 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
1d270 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
1d280 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
1d290 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1d2a0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1d2b0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1d2c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1d2d0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1d2e0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
1d2f0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
1d300 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1d310 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1d320 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1d330 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1d340 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1d350 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1d360 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1d370 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1d380 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
1d390 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1d3a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1d3b0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1d3c0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1d3d0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1d3e0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1d3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d400 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1d410 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1d420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1d430 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1d440 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1d450 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1d460 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1d470 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1d480 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1d490 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1d4a0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1d4b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1d4c0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1d4d0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1d4e0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1d4f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1d500 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1d510 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
1d520 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1d530 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1d540 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1d550 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1d560 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1d570 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1d580 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1d590 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1d5a0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1d5b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d5c0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1d5d0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1d5e0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1d5f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1d600 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1d610 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1d620 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1d630 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1d640 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1d650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1d660 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1d670 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1d680 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1d690 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1d6a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1d6b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1d6c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1d6d0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1d6e0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1d6f0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1d700 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1d710 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1d720 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1d730 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1d740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d750 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1d760 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1d770 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
1d780 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1d790 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1d7a0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1d7b0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1d7c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1d7d0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1d7e0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1d7f0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1d800 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
1d810 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1d820 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
1d830 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d840 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1d850 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1d860 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1d870 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1d880 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1d890 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1d8a0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1d8b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1d8c0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1d8d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1d8e0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1d8f0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1d900 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1d910 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1d920 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1d930 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1d940 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1d950 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1d960 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1d970 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  ifer.)^  ^The va
1d980 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
1d990 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1d9a0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1d9b0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
1d9c0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1d9d0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1d9e0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1d9f0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1da00 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1da10 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
1da20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1da30 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
1da40 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1da50 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
1da60 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1da70 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1da80 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
1da90 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
1daa0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1dab0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
1dac0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
1dad0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
1dae0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
1daf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
1db00 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
1db10 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1db20 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1db30 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
1db40 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1db50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1db60 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1db70 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1db80 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1db90 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1dba0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1dbb0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1dbc0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
1dbd0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
1dbe0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
1dbf0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
1dc00 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
1dc10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1dc20 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
1dc30 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
1dc40 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1dc50 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1dc60 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1dc70 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
1dc80 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
1dc90 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
1dca0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1dcb0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
1dcc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1dcd0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
1dce0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1dcf0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
1dd00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1dd10 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1dd20 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1dd30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
1dd40 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
1dd50 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1dd60 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1dd70 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1dd80 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1dd90 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1dda0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1ddb0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1ddc0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
1ddd0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
1dde0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1ddf0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1de00 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
1de10 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1de20 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1de30 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1de40 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1de50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1de60 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1de70 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1de80 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
1de90 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1dea0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
1deb0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
1dec0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
1ded0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
1dee0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
1def0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
1df00 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
1df10 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
1df20 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
1df30 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1df40 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69  h it. ^If the fi
1df50 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1df60 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1df70 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1df80 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1df90 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1dfa0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1dfb0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1dfc0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1dfd0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1dfe0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1dff0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
1e000 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1e010 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1e020 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1e030 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1e040 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1e050 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1e060 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1e070 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1e080 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e090 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1e0a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e0b0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
1e0c0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
1e0d0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
1e0e0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
1e0f0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
1e100 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
1e110 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
1e120 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
1e130 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
1e140 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
1e150 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1e160 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1e170 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1e180 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1e190 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1e1a0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1e1b0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1e1c0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1e1d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e1e0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
1e1f0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1e200 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
1e210 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1e220 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1e230 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1e240 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1e250 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
1e260 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
1e270 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1e280 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
1e290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1e2a0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
1e2b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1e2c0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
1e2d0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
1e2e0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
1e2f0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
1e300 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
1e310 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
1e320 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
1e330 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
1e340 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1e350 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
1e360 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
1e370 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
1e380 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
1e390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e3a0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
1e3b0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
1e3c0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
1e3d0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
1e3e0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1e3f0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
1e400 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
1e410 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
1e420 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
1e430 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
1e440 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1e450 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1e460 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e470 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
1e480 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1e490 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1e4a0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
1e4b0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
1e4c0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
1e4d0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
1e4e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
1e4f0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1e500 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
1e510 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
1e520 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
1e530 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
1e540 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
1e550 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1e560 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1e570 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1e580 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e590 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1e5a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1e5b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1e5c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1e5d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
1e5e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1e5f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1e600 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1e610 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1e620 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
1e630 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1e640 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
1e650 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
1e660 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e670 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
1e680 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
1e690 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1e6a0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
1e6b0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
1e6c0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
1e6d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
1e6e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1e6f0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
1e700 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
1e710 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
1e720 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1e730 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1e740 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
1e750 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1e760 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1e770 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1e780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
1e790 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
1e7a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
1e7b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1e7c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1e7d0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1e7e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1e7f0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1e800 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1e810 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
1e820 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1e830 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1e840 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1e850 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
1e860 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
1e870 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e880 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
1e890 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1e8a0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1e8b0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1e8c0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1e8d0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1e8e0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1e8f0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1e900 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1e910 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1e920 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1e930 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1e940 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
1e950 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
1e960 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1e970 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1e980 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
1e990 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
1e9a0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
1e9b0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
1e9c0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
1e9d0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
1e9e0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
1e9f0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
1ea00 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
1ea10 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
1ea20 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
1ea30 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1ea40 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
1ea50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1ea60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1ea70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1ea80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ea90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1eaa0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1eab0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1eac0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1ead0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1eae0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1eaf0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1eb00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1eb10 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1eb20 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
1eb30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1eb40 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
1eb50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1eb60 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
1eb70 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
1eb80 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1eb90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1eba0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
1ebb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1ebc0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1ebd0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1ebe0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1ebf0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1ec00 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1ec10 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1ec20 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1ec30 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1ec40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1ec50 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1ec60 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1ec70 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1ec80 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1ec90 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1eca0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
1ecb0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1ecc0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1ecd0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1ece0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
1ecf0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
1ed00 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
1ed10 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
1ed20 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1ed30 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ed40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1ed50 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1ed60 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
1ed70 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
1ed80 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1ed90 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
1eda0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1edb0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1edc0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1edd0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
1ede0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
1edf0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
1ee00 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1ee10 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1ee20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1ee30 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1ee40 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1ee50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1ee60 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1ee70 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1ee80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1ee90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1eea0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1eeb0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1eec0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1eed0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1eee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1eef0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1ef00 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ef10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1ef20 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1ef30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1ef40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ef50 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1ef60 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1ef70 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
1ef80 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1ef90 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1efa0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1efb0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
1efc0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1efd0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1efe0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1eff0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1f000 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1f010 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1f020 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
1f030 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1f040 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1f050 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1f060 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
1f070 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1f080 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1f090 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1f0a0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f0b0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1f0c0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1f0d0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1f0e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f0f0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1f100 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1f110 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1f120 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1f130 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f140 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1f150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f160 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1f170 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1f180 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f190 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1f1a0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1f1b0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1f1c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1f1d0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1f1e0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1f1f0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
1f200 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
1f210 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
1f220 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
1f230 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
1f240 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
1f250 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1f260 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
1f270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f280 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
1f290 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
1f2a0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1f2b0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1f2c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1f2d0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
1f2e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1f2f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f300 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
1f310 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
1f320 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
1f330 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1f340 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1f350 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1f360 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
1f370 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
1f380 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1f390 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
1f3a0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
1f3b0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1f3c0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1f3d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
1f3e0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69   [UPDATE])..*/.i
1f3f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1f400 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1f410 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1f420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1f430 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1f440 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
1f450 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1f460 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
1f470 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
1f480 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
1f490 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
1f4a0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1f4b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1f4c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1f4d0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
1f4e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f4f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f500 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f510 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1f520 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1f530 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
1f540 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f550 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1f560 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1f570 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
1f580 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1f590 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f5a0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1f5b0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1f5c0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f5d0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1f5e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1f5f0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
1f600 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
1f610 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
1f620 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
1f630 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1f640 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1f650 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1f660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f670 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
1f680 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1f690 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1f6a0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f6b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
1f6c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1f6d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1f6e0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
1f6f0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1f700 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
1f710 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1f720 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1f730 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1f740 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1f750 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1f760 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1f770 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1f780 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1f790 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1f7a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1f7b0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1f7c0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1f7d0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1f7e0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1f7f0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1f800 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1f810 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1f820 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1f830 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1f840 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1f850 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1f860 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1f870 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1f880 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1f890 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
1f8a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1f8b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1f8c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1f8d0 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1f8e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1f8f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1f900 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1f910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1f920 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1f930 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
1f940 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1f950 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1f960 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1f970 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
1f980 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
1f990 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1f9a0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
1f9b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
1f9c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
1f9d0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
1f9e0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
1f9f0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1fa00 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1fa10 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1fa20 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1fa30 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1fa40 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
1fa50 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1fa60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1fa70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1fa80 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1fa90 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1faa0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1fab0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1fac0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1fad0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1fae0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
1faf0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
1fb00 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
1fb10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fb20 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1fb30 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
1fb40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1fb50 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
1fb60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1fb70 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
1fb80 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
1fb90 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
1fba0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
1fbb0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
1fbc0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
1fbd0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
1fbe0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
1fbf0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
1fc00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1fc10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
1fc20 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
1fc30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fc40 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
1fc50 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
1fc60 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
1fc70 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
1fc80 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
1fc90 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1fca0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1fcb0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1fcc0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1fcd0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
1fce0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
1fcf0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
1fd00 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1fd10 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
1fd20 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
1fd30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1fd40 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
1fd50 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
1fd60 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
1fd70 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
1fd80 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
1fd90 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
1fda0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
1fdb0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
1fdc0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
1fdd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fde0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
1fdf0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
1fe00 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
1fe10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
1fe20 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
1fe30 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
1fe40 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
1fe50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
1fe60 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
1fe70 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
1fe80 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
1fe90 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
1fea0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
1feb0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
1fec0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1fed0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
1fee0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
1fef0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
1ff00 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
1ff10 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
1ff20 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1ff30 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1ff40 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
1ff50 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1ff60 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
1ff70 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
1ff80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
1ff90 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1ffa0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
1ffb0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1ffc0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
1ffd0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
1ffe0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
1fff0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
20000 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
20010 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
20020 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
20030 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
20040 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
20050 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
20060 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
20070 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
20080 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
20090 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
200a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
200b0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
200c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
200d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
200e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
200f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20100 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
20120 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
20130 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20140 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20160 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
20170 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20180 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20190 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
201a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
201b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
201c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
201d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
201e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
201f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20210 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
20220 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20230 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
20250 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
20260 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
20280 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
20290 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
202a0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
202b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
202c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
202d0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
202e0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
202f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
20300 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
20310 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
20320 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
20330 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
20340 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
20350 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
20360 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
20370 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
20380 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
20390 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
203a0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
203b0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
203c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
203d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
203e0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
203f0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
20400 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
20410 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
20420 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
20430 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
20440 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
20450 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
20460 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
20470 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
20480 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
20490 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
204a0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
204b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
204c0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
204d0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
204e0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
204f0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
20500 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
20510 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
20520 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
20530 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
20540 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
20550 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
20560 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
20570 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
20580 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
20590 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
205a0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
205b0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
205c0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
205d0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
205e0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
205f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
20600 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
20610 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
20620 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
20630 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
20640 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
20650 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
20660 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
20670 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
20680 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
20690 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
206a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
206b0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
206c0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
206d0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
206e0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
206f0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
20700 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
20710 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
20720 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20730 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
20740 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20750 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
20760 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
20770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20780 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
20790 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
207a0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
207b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
207c0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
207d0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
207e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
207f0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
20800 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20810 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
20820 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
20830 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
20840 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
20850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
20860 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
20870 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
20880 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
20890 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
208a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
208b0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
208c0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
208d0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
208e0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
208f0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
20900 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
20910 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
20920 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
20930 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
20940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20950 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20970 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
20980 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
20990 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
209a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
209b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
209c0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
209d0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
209e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
209f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
20a00 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
20a10 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
20a20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
20a30 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
20a40 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
20a50 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
20a60 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
20a70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
20a80 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
20a90 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
20aa0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
20ab0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
20ac0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
20ad0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
20ae0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
20af0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
20b00 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
20b10 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
20b20 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
20b30 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
20b40 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
20b50 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
20b60 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
20b70 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
20b80 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
20b90 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
20ba0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
20bb0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
20bc0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
20bd0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
20be0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
20bf0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
20c00 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
20c10 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
20c20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
20c30 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
20c40 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
20c50 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
20c60 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
20c70 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
20c80 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
20c90 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
20ca0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
20cb0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
20cc0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
20cd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
20ce0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
20cf0 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
20d00 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
20d10 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
20d20 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
20d30 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
20d40 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
20d50 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
20d60 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
20d70 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
20d80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
20d90 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
20da0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
20db0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
20dc0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
20dd0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
20de0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
20df0 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
20e00 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
20e10 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
20e20 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
20e30 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
20e40 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
20e50 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
20e60 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
20e70 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
20e80 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
20e90 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
20ea0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
20eb0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
20ec0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
20ed0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
20ee0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
20ef0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
20f00 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
20f10 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
20f20 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
20f30 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
20f40 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
20f50 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
20f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
20f70 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
20f80 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
20f90 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
20fa0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
20fb0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
20fc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20fd0 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
20fe0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
20ff0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
21000 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
21010 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
21020 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
21030 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
21040 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
21050 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
21060 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
21070 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
21080 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
21090 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
210a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
210b0 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
210c0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
210d0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
210e0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
210f0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
21100 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
21110 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
21120 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
21130 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
21140 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
21150 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
21160 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
21170 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
21180 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21190 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
211a0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
211b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
211c0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
211d0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
211e0 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
211f0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
21200 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
21210 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
21220 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
21230 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
21240 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
21250 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
21260 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
21270 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
21280 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
21290 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
212a0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
212b0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
212c0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
212d0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
212e0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
212f0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
21300 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
21310 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
21320 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
21330 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
21340 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
21350 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
21360 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
21370 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
21380 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21390 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
213a0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
213b0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
213c0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
213d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
213e0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
213f0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
21400 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
21410 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
21420 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
21430 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
21440 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
21450 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
21460 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
21470 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
21480 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
21490 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
214a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
214b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
214c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
214d0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
214e0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
214f0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
21500 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21510 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
21520 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
21530 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
21540 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
21550 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
21560 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
21570 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
21580 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
21590 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
215a0 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
215b0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
215c0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
215d0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
215e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
215f0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
21600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
21610 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65  ata_count(P) the
21620 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
21630 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20  ns in the.** of 
21640 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
21650 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21660 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74  ement] P..*/.int
21670 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
21680 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21690 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
216a0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
216b0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
216c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
216d0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
216e0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
216f0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
21700 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
21710 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
21720 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
21730 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
21740 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
21750 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
21760 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
21770 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
21780 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
21790 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
217a0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
217b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
217c0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
217d0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
217e0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
217f0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
21800 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
21810 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
21820 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
21830 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
21840 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
21850 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
21860 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
21870 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
21880 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
21890 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
218a0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
218b0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
218c0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
218d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
218e0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
218f0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
21900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
21910 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
21920 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
21930 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
21940 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
21950 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
21960 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
21970 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
21980 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
21990 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
219a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
219b0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
219c0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
219d0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
219e0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
219f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21a00 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
21a10 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
21a20 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
21a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
21a40 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
21a50 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
21a60 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
21a70 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
21a80 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
21a90 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
21aa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21ab0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
21ac0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
21ad0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21ae0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
21af0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
21b00 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
21b10 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
21b20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
21b30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
21b40 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
21b50 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
21b60 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
21b70 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
21b80 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
21b90 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
21ba0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
21bb0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
21bc0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
21bd0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
21be0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
21bf0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
21c00 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
21c10 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
21c20 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
21c30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
21c40 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
21c50 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
21c60 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
21c70 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
21c80 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
21c90 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
21ca0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
21cb0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
21cc0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
21cd0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
21ce0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
21cf0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
21d00 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
21d10 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
21d20 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
21d30 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
21d40 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
21d50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
21d60 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
21d70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
21d80 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
21d90 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
21da0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
21db0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
21dc0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
21dd0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
21de0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
21df0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
21e00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e10 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
21e20 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
21e30 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
21e40 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
21e50 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
21e60 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
21e70 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
21e80 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
21e90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21ea0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
21eb0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
21ec0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
21ed0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
21ee0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
21ef0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
21f00 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
21f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
21f20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21f30 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
21f40 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
21f50 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
21f60 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
21f70 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
21f80 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
21f90 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
21fa0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
21fb0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
21fc0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
21fd0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
21fe0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
21ff0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
22000 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
22010 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
22020 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
22030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
22040 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
22050 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
22060 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
22070 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
22080 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
22090 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
220a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
220b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
220c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
220d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
220e0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
220f0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
22100 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
22110 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
22120 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
22130 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
22140 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
22150 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
22160 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
22170 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
22180 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
22190 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
221a0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
221b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
221c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
221d0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
221e0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
221f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
22200 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
22210 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
22220 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
22230 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
22240 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
22250 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
22260 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
22270 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
22280 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
22290 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
222a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
222b0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
222c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
222d0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
222e0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
222f0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
22300 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
22310 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
22320 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65   string..** ^The
22330 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22340 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
22350 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
22360 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
22370 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
22380 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
22390 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
223a0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
223b0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
223c0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
223d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
223e0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
223f0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
22400 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
22410 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
22420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22430 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
22440 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
22450 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
22460 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
22470 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
22480 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
22490 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
224a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
224b0 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
224c0 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
224d0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
224e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
224f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
22510 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
22520 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
22530 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
22540 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
22550 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
22560 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
22570 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
22580 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65  f UTF-8..** ^The
22590 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
225a0 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
225b0 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
225c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
225d0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
225e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
225f0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
22600 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
22610 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
22620 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
22630 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22640 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
22650 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
22660 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
22670 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
22680 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
22690 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
226a0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
226b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
226c0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
226d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
226e0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
226f0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
22700 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
22710 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
22720 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
22730 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
22740 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22750 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
22760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
22770 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
22780 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
22790 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
227a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
227b0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
227c0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
227d0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
227e0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
227f0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
22800 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
22810 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
22820 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
22830 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
22840 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
22850 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
22860 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
22870 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
22880 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
22890 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
228a0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
228b0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
228c0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
228d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
228e0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
228f0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
22900 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
22910 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
22920 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
22930 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
22940 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
22950 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
22960 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
22970 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
22980 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
22990 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
229a0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
229b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
229c0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
229d0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
229e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
229f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22a00 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
22a10 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
22a20 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
22a30 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
22a40 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
22a50 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
22a60 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
22a70 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
22a80 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
22a90 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
22aa0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
22ab0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
22ac0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
22ad0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
22ae0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
22af0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
22b00 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
22b10 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22b20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
22b30 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
22b40 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
22b50 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
22b60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
22b70 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
22b80 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
22b90 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
22ba0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
22bb0 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
22bc0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
22bd0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
22be0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22bf0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
22c00 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
22c10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
22c20 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
22c30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
22c40 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
22c50 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
22c60 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
22c70 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
22c80 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
22c90 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
22ca0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
22cb0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
22cc0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
22cd0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
22ce0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
22cf0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
22d00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
22d10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
22d20 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
22d30 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
22d40 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
22d50 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
22d60 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
22d70 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
22d80 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
22d90 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
22da0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
22db0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
22dc0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
22dd0 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
22de0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
22df0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
22e00 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
22e10 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
22e20 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
22e30 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
22e40 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
22e50 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
22e60 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
22e70 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
22e80 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
22e90 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
22ea0 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
22eb0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
22ec0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
22ed0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
22ee0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
22ef0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
22f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22f10 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
22f20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22f30 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
22f40 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79  lidated..** ^(Ty
22f50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
22f60 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
22f70 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
22f80 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
22f90 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
22fa0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
22fb0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
22fc0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
22fd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
22fe0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
22ff0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
23000 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
23010 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
23020 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
23030 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
23040 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
23050 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
23060 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
23070 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
23080 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
23090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
230a0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
230b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
230c0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
230d0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
230e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
230f0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
23100 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
23110 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
23120 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
23130 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
23140 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23150 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
23160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23170 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
23180 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
23190 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
231a0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
231b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
231c0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
231d0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
231e0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
231f0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
23200 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
23210 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
23220 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
23230 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
23240 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
23250 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
23260 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
23270 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
23280 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
23290 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
232a0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
232b0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
232c0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
232d0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
232e0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
232f0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
23300 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
23310 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
23320 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
23330 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  lidated..**.** ^
23340 28 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20  (The safest and 
23350 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
23360 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
23370 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
23380 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
23390 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
233a0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
233b0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
233c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
233d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
233e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
233f0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
23400 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
23410 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
23420 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
23430 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
23440 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
23450 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
23460 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
23470 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23480 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
23490 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  >)^.**.** In oth
234a0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
234b0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
234c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
234d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
234e0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
234f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23500 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
23510 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
23520 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
23530 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
23540 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
23550 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
23560 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
23570 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23580 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
23590 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
235a0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
235b0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
235c0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
235d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
235e0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
235f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23600 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
23610 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
23620 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23630 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
23640 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
23650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23660 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
23670 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
23680 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
23690 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
236a0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
236b0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
236c0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
236d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
236e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
236f0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
23700 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23710 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
23720 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
23730 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
23740 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
23750 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
23760 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
23770 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
23780 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
23790 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
237a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
237b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
237c0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
237d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
237e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
237f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
23800 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
23810 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
23820 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
23830 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
23840 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
23850 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
23860 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
23870 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
23880 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
23890 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
238a0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
238b0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
238c0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
238d0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
238e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
238f0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
23900 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
23910 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
23920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23930 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
23940 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
23950 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23960 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
23970 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
23980 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
23990 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
239a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
239b0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
239c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
239d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
239e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
239f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
23a00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
23a10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
23a20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
23a30 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
23a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23a50 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
23a60 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
23a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23a80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
23a90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
23aa0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
23ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23ad0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
23ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23af0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23b00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
23b10 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
23b20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
23b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23b40 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
23b50 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
23b60 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
23b70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
23b80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23b90 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
23ba0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
23bb0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
23bc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23bd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74  .** ^If the stat
23be0 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
23bf0 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
23c00 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
23c10 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
23c20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
23c30 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75  urned. ^If execu
23c40 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
23c50 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
23c60 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
23c70 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
23c80 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
23c90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
23ca0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
23cb0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
23cc0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
23cd0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
23ce0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
23cf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
23d00 5e 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20  ^If the virtual 
23d10 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
23d20 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
23d30 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
23d40 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
23d50 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
23d60 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
23d70 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
23d80 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
23d90 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
23da0 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20  .** ^Incomplete 
23db0 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
23dc0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
23dd0 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
23de0 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
23df0 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
23e00 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
23e10 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
23e20 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
23e30 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
23e40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23e50 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
23e60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
23e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23e80 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
23e90 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
23ea0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
23eb0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
23ec0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
23ed0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
23ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
23ef0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
23f00 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
23f10 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
23f20 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
23f30 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
23f40 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
23f50 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
23f60 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
23f70 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
23f80 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
23f90 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
23fa0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
23fb0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
23fc0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
23fd0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
23fe0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
23ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
24000 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
24010 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
24020 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24030 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
24040 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
24050 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
24060 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
24070 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
24080 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24090 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
240a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
240b0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
240c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
240d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
240e0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
240f0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
24100 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
24110 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
24120 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
24130 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
24140 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
24150 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
24160 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
24170 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
24180 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
24190 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
241a0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
241b0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
241c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
241d0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
241e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
241f0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
24200 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
24210 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
24220 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
24230 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
24240 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
24250 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
24260 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
24270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24280 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
24290 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
242a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
242b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
242c0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
242d0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
242e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
242f0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
24300 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
24310 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
24320 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24330 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
24340 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
24350 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24360 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
24370 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e  * ^These two fun
24380 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
24390 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
243a0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
243b0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
243c0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
243d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
243e0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
243f0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
24400 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
24410 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
24420 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
24430 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
24440 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
24450 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68  the.** two is th
24460 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  at the second pa
24470 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d  rameter, the nam
24480 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
24490 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  ) function or.**
244a0 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65   aggregate, is e
244b0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20  ncoded in UTF-8 
244c0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
244d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
244e0 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20  d UTF-16.** for 
244f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24500 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  unction16()..**.
24510 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
24520 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
24530 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24540 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
24550 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
24560 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
24570 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
24580 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
24590 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
245a0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
245b0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
245c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
245d0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
245e0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
245f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24600 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
24610 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
24620 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24630 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
24640 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
24650 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
24660 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
24670 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
24680 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
24690 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
246a0 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
246b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
246c0 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
246d0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
246e0 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
246f0 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
24700 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  .  ^Any attempt 
24710 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
24720 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
24730 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
24740 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
24750 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
24760 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
24770 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24780 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
24790 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
247a0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
247b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
247c0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
247d0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
247e0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
247f0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
24800 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
24810 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
24820 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
24830 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
24840 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
24850 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
24860 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
24870 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24880 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
24890 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
248a0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
248b0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
248c0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
248d0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
248e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
248f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24900 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
24910 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
24920 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
24930 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
24940 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
24950 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
24960 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
24970 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
24980 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24990 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
249a0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
249b0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
249c0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
249d0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
249e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
249f0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
24a00 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
24a10 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
24a20 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
24a30 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
24a40 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
24a50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
24a60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24a70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
24a80 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
24a90 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
24aa0 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
24ab0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
24ac0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
24ad0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
24ae0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
24af0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
24b00 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
24b10 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
24b20 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
24b30 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
24b40 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
24b50 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
24b60 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
24b70 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
24b80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
24b90 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
24ba0 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
24bb0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
24bc0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
24bd0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
24be0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
24bf0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
24c00 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
24c10 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
24c20 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
24c30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
24c40 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
24c50 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
24c60 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
24c70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
24c80 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
24c90 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
24ca0 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
24cb0 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
24cc0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
24cd0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
24ce0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
24cf0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
24d00 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
24d10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
24d20 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
24d30 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
24d40 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
24d50 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
24d60 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
24d70 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
24d80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
24d90 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
24da0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
24db0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
24dc0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
24dd0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
24de0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
24df0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
24e00 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
24e10 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
24e20 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
24e30 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
24e40 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
24e50 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
24e60 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
24e70 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
24e80 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
24e90 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
24ea0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
24eb0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
24ec0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
24ed0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
24ee0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
24ef0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
24f00 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
24f10 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
24f20 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
24f30 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
24f40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
24f50 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
24f60 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
24f70 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
24f80 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
24f90 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
24fa0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
24fb0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
24fc0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
24fd0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
24fe0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
24ff0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
25000 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
25010 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
25020 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
25030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
25040 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
25050 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
25060 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
25070 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
25080 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
25090 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
250a0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
250b0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
250c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
250d0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
250e0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
250f0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
25100 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
25110 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
25120 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
25130 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
25140 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
25150 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
25160 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
25170 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
25180 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
25190 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
251a0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
251b0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
251c0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
251d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
251e0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
251f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 70 70 6c   ^The first appl
25200 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25210 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25220 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
25230 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
25240 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
25250 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
25260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25270 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
25280 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75  ame..** ^Subsequ
25290 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
252a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
252b0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
252c0 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
252d0 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
252e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
252f0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
25300 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
25310 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
25320 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
25330 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
25340 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
25350 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
25360 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
25370 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
25380 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
25390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
253a0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
253b0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
253c0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
253d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
253e0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
253f0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
25400 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
25410 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
25420 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
25430 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25440 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25450 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25460 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25470 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
25480 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
25490 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
254a0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
254b0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
254c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
254d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
254e0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
254f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
25500 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
25510 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
25520 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
25530 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
25540 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25550 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
25560 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
25570 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
25580 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
25590 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
255a0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
255b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
255c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
255d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
255e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
255f0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
25600 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25610 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
25620 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
25630 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
25640 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
25650 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
25660 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
25670 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
25680 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
25690 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
256a0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
256b0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
256c0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
256d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
256e0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
256f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25700 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
25710 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
25720 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
25730 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
25740 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
25750 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
25760 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
25770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25780 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
25790 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
257a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
257b0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
257c0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
257d0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
257e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
257f0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
25800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25810 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
25820 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
25830 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
25840 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
25850 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
25860 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
25870 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
25880 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
25890 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
258a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
258b0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
258c0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
258d0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
258e0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
258f0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
25900 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
25910 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
25920 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
25930 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
25940 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
25950 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
25960 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
25970 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
25980 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
25990 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
259a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
259b0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
259c0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
259d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
259e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
259f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
25a00 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
25a10 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
25a20 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
25a30 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
25a40 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
25a50 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
25a60 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
25a70 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
25a80 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
25a90 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
25aa0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
25ab0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
25ac0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
25ad0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
25ae0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
25af0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
25b00 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
25b10 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
25b20 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
25b30 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
25b40 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
25b50 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
25b60 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
25b70 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
25b80 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
25b90 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
25ba0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
25bb0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
25bc0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
25bd0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
25be0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
25bf0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
25c00 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
25c10 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
25c20 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
25c30 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
25c40 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
25c50 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
25c60 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
25c70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25c80 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
25c90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25ca0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
25cb0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
25cc0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
25cd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
25ce0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
25cf0 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
25d00 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
25d10 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
25d20 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
25d30 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
25d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25d50 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
25d60 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
25d70 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
25d80 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
25d90 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
25da0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
25db0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
25dc0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
25dd0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
25de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25df0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
25e00 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
25e10 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
25e20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25e30 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
25e40 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
25e50 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
25e60 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
25e70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25e80 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
25e90 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
25ea0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
25eb0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
25ec0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
25ed0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
25ee0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
25ef0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
25f00 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
25f10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
25f20 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
25f30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25f40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
25f50 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
25f60 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
25f70 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
25f80 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
25f90 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
25fa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
25fb0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
25fc0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
25fd0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
25fe0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
25ff0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
26000 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
26010 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
26020 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
26030 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
26040 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
26050 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
26060 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
26070 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
26080 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
26090 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
260a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
260b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
260c0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
260d0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
260e0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
260f0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
26100 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
26110 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
26120 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
26130 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
26140 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
26150 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
26160 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
26170 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
26180 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
26190 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
261a0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
261b0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
261c0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
261d0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
261e0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
261f0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
26200 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
26210 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
26220 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
26230 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
26240 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
26250 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
26260 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
26270 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
26280 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
26290 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
262a0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
262b0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
262c0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
262d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
262e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
262f0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
26300 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
26310 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
26320 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
26330 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
26340 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
26350 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
26360 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26370 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
26380 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26390 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
263a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
263b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
263c0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
263d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
263e0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
263f0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
26400 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
26410 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
26420 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
26430 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
26440 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
26450 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
26460 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26470 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
26480 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26490 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
264a0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
264b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
264c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
264d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
264e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
264f0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
26500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
26510 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
26520 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
26530 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26540 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
26550 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
26560 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
26570 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26580 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26590 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
265a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
265b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
265c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
265d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
265e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
265f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26600 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
26610 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
26620 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
26630 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
26640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
26650 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
26660 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
26670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26680 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
26690 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
266a0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 69  **.** Implementi
266b0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
266c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
266d0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
266e0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
266f0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
26700 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
26710 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
26720 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
26730 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
26740 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
26750 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
26760 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
26770 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
26780 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
26790 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
267a0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
267b0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
267c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
267d0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
267e0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
267f0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
26800 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
26810 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
26820 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
26830 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
26840 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
26850 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
26860 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
26870 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
26880 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
26890 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
268a0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
268b0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
268c0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
268d0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
268e0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
268f0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
26900 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
26910 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
26920 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
26930 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
26940 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
26950 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
26960 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
26970 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
26980 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
26990 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
269a0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
269b0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
269c0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
269d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
269e0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
269f0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
26a00 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
26a10 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
26a20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
26a30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26a40 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
26a50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
26a60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
26a70 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
26a80 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
26a90 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
26aa0 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
26ab0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
26ac0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
26ad0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
26ae0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
26af0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
26b00 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
26b10 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
26b20 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
26b30 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
26b40 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
26b50 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
26b60 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
26b70 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
26b80 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
26b90 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
26ba0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
26bb0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
26bc0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
26bd0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
26be0 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
26bf0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
26c00 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
26c10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
26c20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
26c30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26c40 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
26c50 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
26c60 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
26c70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26c80 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
26c90 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
26ca0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
26cb0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
26cc0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
26cd0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
26ce0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
26cf0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
26d00 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
26d10 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
26d20 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
26d30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
26d40 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
26d50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
26d60 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
26d70 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
26d80 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
26d90 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
26da0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
26db0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
26dc0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
26dd0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
26de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26df0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
26e00 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
26e10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
26e20 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
26e30 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
26e40 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
26e50 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
26e60 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
26e70 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
26e80 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
26e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26ea0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
26eb0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26ec0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
26ed0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
26ee0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
26ef0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
26f00 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
26f10 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
26f20 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
26f30 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
26f40 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
26f50 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
26f60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26f70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26f80 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
26f90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
26fa0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
26fb0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
26fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
26fd0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
26fe0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
26ff0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27000 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
27010 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
27020 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
27030 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
27040 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
27050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
27060 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
27070 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
27080 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27090 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
270a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
270b0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
270c0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
270d0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
270e0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
270f0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
27100 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
27110 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
27120 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
27130 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
27140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
27150 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
27160 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
27170 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
27180 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
27190 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
271a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
271b0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
271c0 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
271d0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
271e0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
271f0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
27200 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
27210 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
27220 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
27230 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
27240 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
27250 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
27260 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
27270 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
27280 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
27290 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
272a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
272b0 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
272c0 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
272d0 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
272e0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
272f0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
27300 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
27310 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
27320 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
27330 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
27340 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
27350 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
27360 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
27370 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
27380 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
27390 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
273a0 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
273b0 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
273c0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
273d0 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
273e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
273f0 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
27400 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
27410 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
27420 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
27430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27440 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27450 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27460 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27470 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
27480 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
27490 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
274a0 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
274b0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
274c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
274d0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
274e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
274f0 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74  tion. ^If no met
27500 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
27510 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
27520 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
27530 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
27540 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
27550 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
27560 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
27570 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
27580 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
27590 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
275a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
275b0 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
275c0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
275d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
275e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
275f0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
27600 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
27610 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
27620 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
27630 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
27640 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
27650 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
27660 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27670 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27680 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
27690 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
276a0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
276b0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
276c0 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
276d0 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
276e0 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20  stroyed..** ^If 
276f0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
27700 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
27710 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
27720 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
27730 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
27740 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27750 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27760 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
27770 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
27780 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
27790 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
277a0 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
277b0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
277c0 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
277d0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
277e0 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
277f0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
27800 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
27810 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
27820 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
27830 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
27840 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
27850 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20  ime.  ^The only 
27860 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
27870 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
27880 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
27890 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
278a0 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
278b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
278c0 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
278d0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
278e0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
278f0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
27900 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
27910 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
27920 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
27930 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
27940 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
27950 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a  parameters].)^.*
27960 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27970 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
27980 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
27990 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
279a0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
279b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
279c0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
279d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
279e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
279f0 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
27a00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
27a10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27a20 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
27a30 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
27a40 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27a50 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
27a60 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
27a70 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
27a80 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
27a90 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
27aa0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
27ab0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
27ac0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
27ad0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
27ae0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
27af0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
27b00 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
27b10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
27b20 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
27b30 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
27b40 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
27b50 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
27b60 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
27b70 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
27b80 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
27b90 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
27ba0 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
27bb0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
27bc0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
27bd0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
27be0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
27bf0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
27c00 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
27c10 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
27c20 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
27c30 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
27c40 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
27c50 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
27c60 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
27c70 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
27c80 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
27c90 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
27ca0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
27cb0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
27cc0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
27cd0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
27ce0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
27cf0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
27d00 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
27d10 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
27d20 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
27d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
27d40 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
27d50 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
27d60 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
27d70 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
27d80 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
27d90 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
27da0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27db0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
27dc0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
27dd0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
27de0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
27df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
27e00 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
27e10 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
27e20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
27e30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
27e40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27e50 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
27e60 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27e70 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
27e80 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
27e90 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
27ea0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
27eb0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
27ec0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
27ed0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
27ee0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
27ef0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
27f00 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
27f10 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
27f20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
27f30 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
27f40 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
27f50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
27f60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
27f70 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
27f80 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
27f90 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
27fa0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27fb0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
27fc0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
27fd0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
27fe0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
27ff0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
28000 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
28010 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
28020 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
28030 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28040 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
28050 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
28060 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
28070 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
28080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28090 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
280a0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
280b0 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
280c0 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
280d0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
280e0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
280f0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
28100 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28110 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
28120 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
28130 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
28140 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
28150 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
28160 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28170 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
28180 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
28190 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
281a0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
281b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
281c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
281d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
281e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
281f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
28200 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
28210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
28220 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
28230 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
28240 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
28250 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
28260 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
28270 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
28280 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
28290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
282a0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
282b0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
282c0 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
282d0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
282e0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
282f0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
28300 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
28310 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
28320 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
28330 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
28340 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
28350 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
28360 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
28370 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
28380 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
28390 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
283a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
283b0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
283c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
283d0 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
283e0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
283f0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
28400 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
28410 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
28420 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
28430 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
28440 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
28450 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
28470 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
28480 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
28490 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
284a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
284b0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
284c0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
284d0 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
284e0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
284f0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28500 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28510 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28520 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
28530 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
28540 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
28550 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
28560 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28570 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
28580 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
28590 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
285a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
285b0 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
285c0 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
285d0 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
285e0 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
285f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28600 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
28610 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
28620 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
28630 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
28640 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
28650 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
28660 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
28670 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
28680 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
28690 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
286a0 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
286b0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
286c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
286d0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
286e0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
286f0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
28700 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
28710 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
28720 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28730 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
28740 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
28750 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
28760 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
28770 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
28780 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
28790 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
287a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
287b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
287c0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
287d0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
287e0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
287f0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
28800 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
28810 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
28820 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28830 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
28840 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
28850 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
28860 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28870 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28880 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
28890 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
288a0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
288b0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
288c0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
288d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
288e0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
288f0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
28900 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
28910 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28920 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
28930 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
28940 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
28950 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
28960 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
28970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28980 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
28990 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
289a0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
289b0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
289c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
289d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
289e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
289f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28a00 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
28a10 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
28a20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
28a30 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
28a40 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
28a50 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
28a60 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
28a70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28a80 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28a90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28aa0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
28ab0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
28ac0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
28ad0 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
28ae0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28af0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
28b00 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
28b10 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
28b20 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
28b30 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
28b40 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
28b50 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
28b60 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
28b70 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
28b80 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28b90 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28ba0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
28bb0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
28bc0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
28bd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
28be0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
28bf0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
28c00 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
28c10 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
28c20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
28c30 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
28c40 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
28c50 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
28c60 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
28c70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28c80 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
28c90 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
28ca0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
28cb0 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
28cc0 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
28cd0 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
28ce0 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
28cf0 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
28d00 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
28d10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
28d20 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
28d30 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
28d40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
28d50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28d60 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
28d70 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
28d80 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
28d90 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
28da0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
28db0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
28dc0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
28dd0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
28de0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
28df0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
28e00 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
28e10 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
28e20 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
28e30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
28e40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28e50 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
28e60 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
28e70 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
28e80 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
28e90 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
28ea0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
28eb0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
28ec0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
28ed0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
28ee0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
28ef0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
28f00 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28f10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
28f20 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
28f30 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
28f40 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
28f50 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
28f60 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
28f70 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
28f80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
28f90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
28fa0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
28fb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
28fc0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
28fd0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
28fe0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
28ff0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
29000 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
29010 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
29020 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
29030 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
29040 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
29050 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
29060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29070 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29080 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29090 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
290a0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
290b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
290c0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
290d0 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
290e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
290f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
29100 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
29110 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
29120 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
29130 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
29140 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
29150 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
29160 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
29170 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
29180 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
29190 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
291a0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
291b0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
291c0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
291d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
291e0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
291f0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
29200 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29210 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
29220 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
29230 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
29240 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29250 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29260 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
29270 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
29280 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
29290 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
292a0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
292b0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
292c0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
292d0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
292e0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
292f0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
29300 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
29310 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
29320 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29330 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
29340 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
29350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
29360 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
29370 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29380 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
29390 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
293a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
293b0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
293c0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
293d0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
293e0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
293f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29400 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
29410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29420 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
29430 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
29440 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
29450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29460 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
29470 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
29480 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
29490 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
294a0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
294b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
294c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
294d0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
294e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
294f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29500 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
29510 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
29520 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
29530 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29540 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
29550 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
29560 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29570 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
29580 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
29590 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
295a0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
295b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
295c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
295d0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
295e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
295f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
29600 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29610 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29620 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
29630 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29640 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
29650 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29660 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29670 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
29680 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29690 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
296a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
296b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
296c0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
296d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
296e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
296f0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
29700 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29710 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
29720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
29730 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
29740 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
29750 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
29760 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29770 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
29780 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
29790 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
297a0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ences.**.** Thes
297b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
297c0 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
297d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
297e0 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64  ces to the.** [d
297f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29800 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
29810 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
29820 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
29830 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
29840 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
29850 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
29860 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
29870 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
29880 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29890 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
298a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
298b0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
298c0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
298d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
298e0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e  collation16(). ^
298f0 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
29900 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
29910 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
29920 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
29930 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  nt..**.** ^The t
29940 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
29950 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
29960 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
29970 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
29980 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
29990 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
299a0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
299b0 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
299c0 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
299d0 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
299e0 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
299f0 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
29a00 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
29a10 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
29a20 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
29a30 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
29a40 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a  pectively. ^The.
29a50 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
29a60 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
29a70 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74  [SQLITE_UTF16] t
29a80 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
29a90 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65  the routine.** e
29aa0 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
29ab0 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72  to be UTF-16 str
29ac0 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69  ings in the nati
29ad0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f  ve byte order, o
29ae0 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  r the.** argumen
29af0 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45  t can be [SQLITE
29b00 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
29b10 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f  if the.** the ro
29b20 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
29b30 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
29b40 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
29b50 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
29b60 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
29b70 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
29b80 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
29b90 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
29ba0 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
29bb0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
29bc0 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
29bd0 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55  t.  ^If it is NU
29be0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
29bf0 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
29c00 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
29c10 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
29c20 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
29c30 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
29c40 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d  e)..** ^Each tim
29c50 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
29c60 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
29c70 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
29c80 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
29c90 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
29ca0 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
29cb0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
29cc0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
29cd0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
29ce0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29cf0 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
29d00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29d10 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
29d20 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20   ^The remaining 
29d30 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
29d40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
29d50 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
29d60 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
29d70 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
29d80 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
29d90 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
29da0 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
29db0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
29dc0 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
29dd0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
29de0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
29df0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
29e00 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
29e10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
29e20 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
29e30 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
29e40 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
29e50 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
29e60 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
29e70 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
29e80 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
29e90 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
29ea0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
29eb0 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
29ec0 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
29ed0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
29ee0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
29ef0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
29f00 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
29f10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
29f20 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
29f30 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
29f40 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
29f50 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
29f60 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
29f70 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65  lation.  ^The de
29f80 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
29f90 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
29fa0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
29fb0 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
29fc0 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
29fd0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29fe0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
29ff0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
2a000 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2a010 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f  ion_v2()..** ^Co
2a020 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
2a030 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
2a040 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
2a050 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
2a060 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
2a070 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
2a080 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
2a090 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a0a0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
2a0b0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2a0c0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
2a0d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2a0e0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a0f0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2a100 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2a110 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2a120 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2a130 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a140 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2a150 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a160 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2a170 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2a180 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2a190 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2a1a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2a1b0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2a1c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a1d0 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2a1e0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2a1f0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2a200 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2a210 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2a220 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2a230 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2a240 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
2a250 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2a260 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
2a270 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a280 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2a290 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2a2a0 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2a2b0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2a2c0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2a2d0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2a2e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2a2f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2a300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a310 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
2a320 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
2a330 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
2a340 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
2a350 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
2a360 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
2a370 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2a380 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
2a390 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
2a3a0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
2a3b0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
2a3c0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2a3d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
2a3e0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2a3f0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
2a400 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2a410 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
2a420 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a430 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
2a440 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
2a450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a460 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
2a470 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
2a480 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
2a490 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
2a4a0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2a4b0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
2a4c0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
2a4d0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
2a4e0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2a4f0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
2a500 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
2a510 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2a520 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
2a530 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
2a540 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
2a550 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
2a560 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
2a570 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
2a580 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2a590 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
2a5a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2a5b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a5c0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2a5d0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2a5e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2a5f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a600 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2a610 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2a620 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2a630 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a640 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2a650 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2a660 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
2a670 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2a680 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
2a690 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2a6a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2a6b0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
2a6c0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
2a6d0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
2a6e0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2a6f0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
2a700 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
2a710 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a720 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2a730 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2a740 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2a750 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
2a760 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2a770 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
2a780 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
2a790 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
2a7a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2a7b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
2a7c0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2a7d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
2a7e0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2a7f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a800 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
2a810 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a820 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2a830 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2a840 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2a850 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2a860 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2a870 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2a880 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2a890 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2a8a0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2a8b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2a8c0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2a8d0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2a8e0 29 3b 0a 0a 23 69 66 20 53 51 4c 49 54 45 5f 48  );..#if SQLITE_H
2a8f0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
2a900 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
2a910 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
2a920 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
2a930 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
2a940 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
2a950 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
2a960 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
2a970 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
2a980 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
2a990 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
2a9a0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
2a9b0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
2a9c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a9d0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
2a9e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a9f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2aa00 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2aa10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2aa20 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2aa30 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
2aa40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
2aa50 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
2aa60 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
2aa70 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
2aa80 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
2aa90 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
2aaa0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
2aab0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
2aac0 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
2aad0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
2aae0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
2aaf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
2ab00 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2ab10 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2ab20 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2ab30 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2ab40 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2ab50 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
2ab60 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
2ab70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ab80 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ab90 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
2aba0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
2abb0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
2abc0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
2abd0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
2abe0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
2abf0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
2ac00 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
2ac10 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
2ac20 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
2ac30 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
2ac40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2ac50 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2ac60 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
2ac70 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
2ac80 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
2ac90 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
2aca0 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
2acb0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
2acc0 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
2acd0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
2ace0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
2acf0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
2ad00 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2ad10 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
2ad20 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
2ad30 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
2ad40 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
2ad50 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
2ad60 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
2ad70 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
2ad80 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
2ad90 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
2ada0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
2adb0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
2adc0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
2add0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ade0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
2adf0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
2ae00 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
2ae10 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2ae20 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
2ae30 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
2ae40 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
2ae50 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
2ae60 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ameter..**.** ^I
2ae70 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2ae80 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2ae90 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2aea0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2aeb0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2aec0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2aed0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2aee0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2aef0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2af00 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62  econd. ^The numb
2af10 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2af20 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2af30 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
2af40 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
2af50 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
2af60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2af70 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
2af80 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
2af90 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
2afa0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
2afb0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
2afc0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
2afd0 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
2afe0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
2aff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b000 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
2b010 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
2b020 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
2b030 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
2b040 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
2b050 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2b060 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
2b070 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
2b080 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
2b090 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
2b0a0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
2b0b0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
2b0c0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
2b0d0 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
2b0e0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
2b0f0 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
2b100 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
2b110 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
2b120 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
2b130 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
2b140 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2b150 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
2b160 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
2b170 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
2b180 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
2b190 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
2b1a0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2b1b0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2b1c0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
2b1d0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
2b1e0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
2b1f0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
2b200 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2b210 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2b220 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
2b230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b240 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
2b250 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
2b260 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
2b270 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
2b280 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
2b290 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
2b2a0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
2b2b0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
2b2c0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
2b2d0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
2b2e0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
2b2f0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
2b300 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
2b310 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2b320 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
2b330 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
2b340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
2b350 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2b360 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
2b370 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2b380 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
2b390 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
2b3a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2b3b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2b3c0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
2b3d0 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
2b3e0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2b3f0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
2b400 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
2b410 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
2b420 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2b430 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
2b440 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
2b450 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
2b460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
2b470 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
2b480 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
2b490 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
2b4a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b4b0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
2b4c0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
2b4d0 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
2b4e0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
2b4f0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
2b500 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
2b510 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
2b520 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2b530 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2b540 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
2b550 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
2b560 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2b570 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
2b580 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
2b590 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
2b5a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
2b5b0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
2b5c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2b5d0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
2b5e0 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
2b5f0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
2b600 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
2b610 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2b620 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
2b630 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
2b640 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
2b650 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
2b660 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b670 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
2b680 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
2b690 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
2b6a0 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
2b6b0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
2b6c0 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
2b6d0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
2b6e0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
2b6f0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
2b700 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
2b710 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
2b720 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
2b730 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
2b740 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
2b750 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
2b760 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
2b770 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
2b780 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
2b790 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
2b7a0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
2b7b0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
2b7c0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
2b7d0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
2b7e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
2b7f0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
2b800 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
2b810 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
2b820 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
2b830 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
2b840 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
2b850 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
2b860 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
2b870 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2b880 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
2b890 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
2b8a0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
2b8b0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
2b8c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
2b8d0 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
2b8e0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
2b8f0 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
2b900 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2b910 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
2b920 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
2b930 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
2b940 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2b950 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2b960 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
2b970 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
2b980 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
2b990 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
2b9a0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
2b9b0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
2b9c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2b9d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
2b9e0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
2b9f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
2ba00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ba10 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
2ba20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
2ba30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
2ba40 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
2ba50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ba60 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
2ba70 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
2ba80 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
2ba90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2baa0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
2bab0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2bac0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
2bad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bae0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
2baf0 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
2bb00 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
2bb10 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
2bb20 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
2bb30 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
2bb40 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
2bb50 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
2bb60 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2bb70 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
2bb80 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
2bb90 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2bba0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
2bbb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2bbc0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
2bbd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bbe0 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74  ] after.** pStmt
2bbf0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2bc00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2bc10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20  onnection] pDb. 
2bc20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55   ^If pStmt is NU
2bc30 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
2bc40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2bc50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2bc60 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
2bc70 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
2bc80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2bc90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bca0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66  ection pDb.  ^If
2bcb0 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
2bcc0 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
2bcd0 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
2bce0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
2bcf0 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
2bd00 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
2bd10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bd20 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
2bd30 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  n a call to.** [
2bd40 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2bd50 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66  t(D,S)] must ref
2bd60 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61  er to an open da
2bd70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2bd80 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
2bd90 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
2bda0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
2bdb0 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74  r..*/.sqlite3_st
2bdc0 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
2bdd0 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
2bde0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
2bdf0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2be00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
2be10 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
2be20 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2be30 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2be40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2be50 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2be60 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2be70 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2be80 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2be90 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2bea0 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
2beb0 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
2bec0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2bed0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2bee0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
2bef0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2bf00 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2bf10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2bf20 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
2bf30 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  en..** ^The sqli
2bf40 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2bf50 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2bf60 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2bf70 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
2bf80 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
2bf90 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
2bfa0 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b  ion is [ROLLBACK
2bfb0 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e   | rolled back].
2bfc0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2bfd0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2bfe0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
2bff0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2c000 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2c010 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2c020 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2c030 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70  idden..** ^The p
2c040 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
2c050 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
2c060 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
2c070 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
2c080 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
2c090 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
2c0a0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
2c0b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
2c0c0 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
2c0d0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
2c0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c0f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2c100 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74  D,C,P) and sqlit
2c110 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2c120 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
2c130 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20  s.** return the 
2c140 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
2c150 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2c160 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  l of the same fu
2c170 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65  nction.** on the
2c180 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2c190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
2c1a0 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
2c1b0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
2c1c0 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f   each function o
2c1d0 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n D..**.** The c
2c1e0 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
2c1f0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2c200 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2c210 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2c220 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c230 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2c240 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
2c250 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2c260 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2c270 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c280 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2c290 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2c2a0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2c2b0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2c2c0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2c2d0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2c2e0 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
2c2f0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2c300 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2c310 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
2c320 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c330 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2c340 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2c350 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2c360 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c370 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2c380 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2c390 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2c3a0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69  aph..**.** ^Regi
2c3b0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
2c3c0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2c3d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2c3e0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63  *.** ^When the c
2c3f0 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62  ommit hook callb
2c400 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ack routine retu
2c410 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43  rns zero, the [C
2c420 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74  OMMIT].** operat
2c430 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74  ion is allowed t
2c440 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61  o continue norma
2c450 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f  lly.  ^If the co
2c460 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74  mmit hook.** ret
2c470 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
2c480 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  hen the [COMMIT]
2c490 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2c4a0 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  to a [ROLLBACK].
2c4b0 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
2c4c0 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65  k hook is invoke
2c4d0 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20  d on a rollback 
2c4e0 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f  that results fro
2c4f0 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f  m a commit.** ho
2c500 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e  ok returning non
2c510 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69  -zero, just as i
2c520 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20  t would be with 
2c530 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61  any other rollba
2c540 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  ck..**.** ^For t
2c550 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
2c560 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
2c570 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
2c580 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
2c590 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
2c5a0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
2c5b0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
2c5c0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
2c5d0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
2c5e0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
2c5f0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
2c600 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
2c610 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2c620 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2c630 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2c640 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
2c650 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2c660 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2c670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c680 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
2c690 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ed..** ^The roll
2c6a0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
2c6b0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
2c6c0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2c6d0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
2c6e0 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
2c6f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
2c700 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a  ed non-zero..**.
2c710 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2c720 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2c730 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2c740 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2c750 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2c760 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2c770 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2c780 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2c790 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2c7a0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2c7b0 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2c7c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c7d0 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2c7e0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2c7f0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2c800 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2c810 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2c820 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2c830 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2c840 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2c850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2c860 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2c870 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2c880 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2c890 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2c8a0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2c8b0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2c8c0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2c8d0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2c8e0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2c8f0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2c900 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2c910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c920 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2c930 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2c940 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2c950 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2c960 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2c970 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2c980 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2c990 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2c9a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2c9b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2c9c0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2c9d0 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2c9e0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2c9f0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2ca00 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2ca10 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2ca20 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2ca30 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2ca40 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2ca50 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2ca60 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2ca70 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2ca80 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2ca90 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2caa0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2cab0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2cac0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2cad0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2cae0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2caf0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2cb00 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2cb10 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2cb20 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2cb30 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2cb40 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2cb50 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2cb60 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2cb70 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2cb80 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2cb90 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2cba0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2cbb0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2cbc0 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2cbd0 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2cbe0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2cbf0 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2cc00 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2cc10 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2cc20 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2cc30 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2cc40 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2cc50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2cc60 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2cc70 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2cc80 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2cc90 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2cca0 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2ccb0 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2ccc0 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2ccd0 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2cce0 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2ccf0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2cd00 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2cd10 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2cd20 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2cd30 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2cd40 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2cd50 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2cd60 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2cd70 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2cd80 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2cd90 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2cda0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2cdb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2cdc0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2cdd0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2cde0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2cdf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2ce00 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2ce10 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2ce20 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2ce30 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2ce40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2ce50 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2ce60 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2ce70 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2ce80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2ce90 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2cea0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2ceb0 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2cec0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2ced0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2cee0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2cef0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2cf00 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2cf10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2cf20 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2cf30 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2cf40 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2cf50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cf60 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2cf70 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2cf80 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2cf90 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2cfa0 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2cfb0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2cfc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cfd0 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2cfe0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2cff0 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2d000 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2d010 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2d020 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d030 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2d040 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2d050 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2d060 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2d070 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2d080 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2d090 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2d0a0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2d0b0 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2d0c0 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2d0d0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2d0e0 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2d0f0 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2d100 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2d110 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2d120 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2d130 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2d140 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2d150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2d160 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2d170 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2d180 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2d190 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2d1a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2d1b0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2d1c0 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2d1d0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2d1e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2d1f0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2d200 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2d210 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2d220 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2d230 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2d240 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2d250 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2d260 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2d270 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2d280 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2d290 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2d2a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2d2b0 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2d2c0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2d2d0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2d2e0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2d2f0 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2d300 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2d310 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2d320 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2d330 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2d340 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2d350 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2d360 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2d370 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d380 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2d390 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d3a0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2d3b0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2d3c0 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2d3d0 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2d3e0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2d3f0 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2d400 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2d410 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2d420 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2d430 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2d440 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2d450 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2d460 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2d470 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2d480 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2d490 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2d4a0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2d4b0 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2d4c0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2d4d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2d4e0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2d4f0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2d500 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2d510 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2d520 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2d530 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2d540 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2d550 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2d560 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2d570 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2d580 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2d590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2d5a0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2d5b0 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2d5c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2d5d0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2d5e0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2d5f0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2d600 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2d610 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2d620 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2d630 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2d640 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2d650 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2d660 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2d670 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2d680 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2d690 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2d6a0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2d6b0 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2d6c0 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2d6d0 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2d6e0 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2d6f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d700 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2d710 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2d720 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2d730 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2d740 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2d750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2d760 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2d770 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d780 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2d790 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2d7a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d7b0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2d7c0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2d7d0 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2d7e0 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2d7f0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2d800 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2d810 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2d820 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2d830 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2d840 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2d850 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2d860 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2d870 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2d880 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2d890 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2d8a0 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2d8b0 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2d8c0 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2d8d0 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2d8e0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2d8f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2d900 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2d910 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2d920 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2d930 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2d940 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2d950 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2d960 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2d970 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2d980 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2d990 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2d9a0 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2d9b0 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2d9c0 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2d9d0 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2d9e0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2d9f0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2da00 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2da10 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2da20 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2da30 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2da40 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2da50 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2da60 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2da70 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2da80 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2da90 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2daa0 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2dab0 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2dac0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2dad0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2dae0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2daf0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2db00 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2db10 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2db20 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2db30 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2db40 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2db50 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2db60 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2db70 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2db80 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2db90 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2dba0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2dbb0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2dbc0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2dbd0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2dbe0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2dbf0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2dc00 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2dc10 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2dc20 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2dc30 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2dc40 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2dc50 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2dc60 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2dc70 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2dc80 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2dc90 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2dca0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2dcb0 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2dcc0 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2dcd0 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2dce0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2dcf0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2dd00 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2dd10 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2dd20 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2dd30 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2dd40 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2dd50 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2dd60 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2dd70 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2dd80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2dd90 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2dda0 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2ddb0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2ddc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2ddd0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2dde0 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2ddf0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2de00 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2de10 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2de20 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2de30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2de40 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2de50 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2de60 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2de70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2de80 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
2de90 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2dea0 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2deb0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2dec0 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2ded0 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
2dee0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2def0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2df00 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2df10 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2df20 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
2df30 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2df40 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2df50 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2df60 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2df70 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2df80 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
2df90 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
2dfa0 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
2dfb0 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
2dfc0 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
2dfd0 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
2dfe0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
2dff0 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
2e000 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
2e010 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
2e020 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2e030 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2e040 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2e050 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
2e060 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
2e070 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
2e080 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
2e090 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
2e0a0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
2e0b0 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
2e0c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
2e0d0 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2e0e0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2e0f0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2e100 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2e110 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2e120 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2e130 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2e140 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
2e150 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2e160 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2e170 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2e180 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2e190 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2e1a0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2e1b0 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
2e1c0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2e1d0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2e1e0 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2e1f0 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2e200 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2e210 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2e220 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2e230 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2e240 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2e250 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2e260 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2e270 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2e280 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2e290 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2e2a0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2e2b0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2e2c0 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2e2d0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2e2e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2e2f0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2e300 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2e310 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2e320 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2e330 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2e340 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2e350 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2e360 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2e370 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2e380 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2e390 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
2e3a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2e3b0 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2e3c0 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2e3d0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2e3e0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2e3f0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2e400 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2e410 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2e420 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2e430 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2e440 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2e450 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2e460 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2e470 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2e480 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2e490 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2e4a0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2e4b0 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2e4c0 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2e4d0 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2e4e0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2e4f0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2e500 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2e510 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2e520 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2e530 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2e540 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2e550 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2e560 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
2e570 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
2e580 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
2e590 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2e5a0 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
2e5b0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2e5c0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2e5d0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
2e5e0 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2e5f0 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2e600 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2e610 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2e620 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2e630 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2e640 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2e650 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2e660 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2e670 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
2e680 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
2e690 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
2e6a0 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
2e6b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
2e6c0 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
2e6d0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
2e6e0 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
2e6f0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
2e700 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
2e710 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
2e720 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
2e730 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
2e740 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
2e750 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
2e760 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2e770 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
2e780 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
2e790 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2e7a0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
2e7b0 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2e7c0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2e7d0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2e7e0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2e7f0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2e800 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2e810 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2e820 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
2e830 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
2e840 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
2e850 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
2e860 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2e870 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
2e880 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e890 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2e8a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e8b0 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
2e8c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2e8d0 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
2e8e0 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
2e8f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2e900 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
2e910 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
2e920 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2e930 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
2e940 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
2e950 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
2e960 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2e970 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
2e980 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
2e990 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
2e9a0 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
2e9b0 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
2e9c0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2e9d0 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
2e9e0 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
2e9f0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
2ea00 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
2ea10 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2ea20 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
2ea30 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
2ea40 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
2ea50 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2ea60 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2ea70 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
2ea80 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
2ea90 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
2eaa0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
2eab0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2eac0 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2ead0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2eae0 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2eaf0 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2eb00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2eb10 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2eb20 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2eb30 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2eb40 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2eb50 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2eb60 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
2eb70 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
2eb80 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2eb90 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
2eba0 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2ebb0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2ebc0 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2ebd0 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
2ebe0 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
2ebf0 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
2ec00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2ec10 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2ec20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ec30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
2ec40 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
2ec50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2ec60 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
2ec70 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
2ec80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
2ec90 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
2eca0 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
2ecb0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2ecc0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2ecd0 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2ece0 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
2ecf0 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2ed00 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2ed10 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2ed20 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
2ed30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2ed40 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
2ed50 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
2ed60 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
2ed70 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
2ed80 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
2ed90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
2eda0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2edb0 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2edc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
2edd0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2ede0 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
2edf0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
2ee00 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
2ee10 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
2ee20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2ee30 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
2ee40 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2ee50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
2ee60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
2ee70 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
2ee80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2ee90 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
2eea0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
2eeb0 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
2eec0 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
2eed0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2eee0 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
2eef0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
2ef00 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
2ef10 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
2ef20 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
2ef30 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
2ef40 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
2ef50 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
2ef60 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
2ef70 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
2ef80 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
2ef90 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
2efa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2efb0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
2efc0 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
2efd0 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
2efe0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
2eff0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
2f000 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
2f010 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
2f020 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
2f030 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
2f040 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
2f050 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
2f060 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
2f070 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
2f080 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
2f090 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
2f0a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
2f0b0 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
2f0c0 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
2f0d0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2f0e0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
2f0f0 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
2f100 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
2f110 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
2f120 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
2f130 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
2f140 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
2f150 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2f160 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
2f170 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
2f180 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
2f190 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
2f1a0 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
2f1b0 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
2f1c0 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
2f1d0 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
2f1e0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2f1f0 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
2f200 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
2f210 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f220 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
2f230 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
2f240 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
2f250 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
2f260 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
2f270 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
2f280 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
2f290 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
2f2a0 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
2f2b0 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
2f2c0 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
2f2d0 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
2f2e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f2f0 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
2f300 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2f310 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2f320 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
2f330 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
2f340 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
2f350 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2f360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
2f370 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
2f380 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
2f390 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
2f3a0 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2f3b0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
2f3c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
2f3d0 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
2f3e0 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
2f3f0 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
2f400 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
2f410 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
2f420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f430 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
2f440 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2f450 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2f460 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
2f470 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
2f480 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
2f490 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
2f4a0 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
2f4b0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
2f4c0 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
2f4d0 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
2f4e0 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
2f4f0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
2f500 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
2f510 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
2f520 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
2f530 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f540 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
2f550 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
2f560 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
2f570 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2f580 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
2f590 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
2f5a0 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
2f5b0 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
2f5c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
2f5d0 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
2f5e0 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
2f5f0 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
2f600 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
2f610 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
2f620 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
2f630 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
2f640 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2f650 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
2f660 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
2f670 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
2f680 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
2f690 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2f6a0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a  (void);../*.****
2f6b0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
2f6c0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
2f6d0 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
2f6e0 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
2f6f0 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  *.**.** The inte
2f700 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
2f710 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2f720 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
2f730 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
2f740 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
2f750 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
2f760 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
2f770 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
2f780 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
2f790 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
2f7a0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
2f7b0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
2f7c0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
2f7d0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
2f7e0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2f7f0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
2f800 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
2f810 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
2f820 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
2f830 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
2f840 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
2f850 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
2f860 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
2f870 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
2f880 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
2f890 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
2f8a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2f8b0 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
2f8c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2f8d0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2f8e0 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
2f8f0 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
2f900 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2f910 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
2f920 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
2f930 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2f940 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
2f950 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
2f960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
2f970 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65  rtual Table Obje
2f980 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2f990 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
2f9a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
2f9b0 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d  dule}.** EXPERIM
2f9c0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ENTAL.**.** This
2f9d0 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65   structure, some
2f9e0 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61  times called a a
2f9f0 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   "virtual table 
2fa00 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66  module", .** def
2fa10 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65  ines the impleme
2fa20 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69  ntation of a [vi
2fa30 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20  rtual tables].  
2fa40 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
2fa50 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74  re consists most
2fa60 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
2fa70 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
2fa80 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74  .** ^A virtual t
2fa90 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63  able module is c
2faa0 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e  reated by fillin
2fab0 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e  g in a persisten
2fac0 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  t.** instance of
2fad0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
2fae0 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f  and passing a po
2faf0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  inter to that in
2fb00 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71  stance.** to [sq
2fb10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2fb20 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ule()] or [sqlit
2fb30 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
2fb40 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
2fb50 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
2fb60 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
2fb70 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
2fb80 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
2fb90 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
2fba0 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
2fbb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
2fbc0 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
2fbd0 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
2fbe0 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
2fbf0 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
2fc00 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
2fc10 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
2fc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
2fc30 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
2fc40 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
2fc50 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
2fc60 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
2fc70 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
2fc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2fc90 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
2fca0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
2fcb0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2fcc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
2fcd0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
2fce0 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
2fcf0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
2fd00 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
2fd10 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2fd20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
2fd30 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
2fd40 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
2fd50 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
2fd60 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
2fd70 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
2fd80 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
2fd90 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2fda0 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
2fdb0 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
2fdc0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2fdd0 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
2fde0 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
2fdf0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2fe00 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
2fe10 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
2fe20 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2fe30 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
2fe40 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
2fe50 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fe60 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
2fe70 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
2fe80 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
2fe90 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
2fea0 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
2feb0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
2fec0 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
2fed0 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
2fee0 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
2fef0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2ff00 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
2ff10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2ff20 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2ff30 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
2ff40 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2ff50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ff60 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
2ff70 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
2ff80 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
2ff90 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
2ffa0 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
2ffb0 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
2ffc0 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
2ffd0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
2ffe0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
2fff0 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
30000 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30010 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
30020 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
30030 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30040 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
30050 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30060 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
30070 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
30080 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30090 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
300a0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
300b0 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
300c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
300d0 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
300e0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
300f0 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
30100 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30120 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30130 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
30140 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
30150 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
30160 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
30170 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
30180 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
30190 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
301a0 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
301b0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f  rmation.** KEYWO
301c0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64  RDS: sqlite3_ind
301d0 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52  ex_info.** EXPER
301e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
301f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
30200 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
30210 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
30220 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a  ures is used to.
30230 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74  ** pass informat
30240 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63  ion into and rec
30250 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66  eive the reply f
30260 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e  rom the [xBestIn
30270 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  dex].** method o
30280 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
30290 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65  le module].  The
302a0 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a   fields under **
302b0 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65  Inputs** are the
302c0 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42  .** inputs to xB
302d0 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65  estIndex and are
302e0 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65   read-only.  xBe
302f0 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20  stIndex inserts 
30300 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  its.** results i
30310 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74  nto the **Output
30320 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a  s** fields..**.*
30330 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61  * ^(The aConstra
30340 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f  int[] array reco
30350 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rds WHERE clause
30360 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20   constraints of 
30370 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  the form:.**.** 
30380 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  <pre>column OP e
30390 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  xpr</pre>.**.** 
303a0 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
303b0 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
303c0 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e  , or &gt;=.)^  ^
303d0 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20  (The particular 
303e0 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73  operator is.** s
303f0 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72  tored in aConstr
30400 61 69 6e 74 5b 5d 2e 6f 70 2e 29 5e 20 20 5e 28  aint[].op.)^  ^(
30410 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
30420 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
30430 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61  d in.** aConstra
30440 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e  int[].iColumn.)^
30450 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b    ^(aConstraint[
30460 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45  ].usable is TRUE
30470 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20   if the.** expr 
30480 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  on the right-han
30490 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76  d side can be ev
304a0 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75  aluated (and thu
304b0 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  s the constraint
304c0 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61  .** is usable) a
304d0 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63  nd false if it c
304e0 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  annot.)^.**.** ^
304f0 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75  The optimizer au
30500 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65  tomatically inve
30510 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65  rts terms of the
30520 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63   form "expr OP c
30530 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61  olumn".** and ma
30540 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69  kes other simpli
30550 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65  fications to the
30560 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e   WHERE clause in
30570 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a   an attempt to.*
30580 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48  * get as many WH
30590 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
305a0 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73   into the form s
305b0 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f  hown above as po
305c0 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20  ssible..** ^The 
305d0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
305e0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
305f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
30600 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  rms that are.** 
30610 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20  relevant to the 
30620 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
30630 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
30640 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ueried..**.** ^I
30650 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
30660 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
30670 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
30680 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
30690 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61   ^Each term of a
306a0 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
306b0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
306c0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
306d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
306e0 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
306f0 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
30700 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
30710 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
30720 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
30730 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
30740 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61   xFilter.  ^If a
30750 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
30760 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
30770 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
30780 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
30790 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
307a0 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
307b0 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
307c0 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
307d0 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e  argv.  ^(If aCon
307e0 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
307f0 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
30800 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
30810 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
30820 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
30830 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
30840 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
30850 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
30860 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e  ain by SQLite.)^
30870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e  .**.** ^The idxN
30880 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61  um and idxPtr va
30890 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65  lues are recorde
308a0 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74  d and passed int
308b0 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65  o the.** [xFilte
308c0 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b  r] method..** ^[
308d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
308e0 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
308f0 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e  idxPtr if and on
30900 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46  ly if.** needToF
30910 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75  reeIdxPtr is tru
30920 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72  e..**.** ^The or
30930 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
30940 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
30950 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b  from [xFilter]/[
30960 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75  xNext] will occu
30970 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
30980 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
30990 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
309a0 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
309b0 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
309c0 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
309d0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
309e0 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f  ^The estimatedCo
309f0 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
30a00 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
30a10 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
30a20 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
30a30 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
30a40 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
30a50 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
30a60 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
30a70 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
30a80 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
30a90 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
30aa0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
30ab0 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
30ac0 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
30ad0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
30ae0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
30af0 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
30b00 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
30b10 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
30b20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
30b30 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
30b40 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
30b50 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
30b60 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
30b70 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
30b80 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
30b90 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
30ba0 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
30bb0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
30bc0 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
30bd0 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
30be0 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
30bf0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
30c00 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
30c10 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
30c20 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
30c30 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
30c40 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
30c50 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
30c60 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
30c70 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
30c80 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
30c90 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
30ca0 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
30cb0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
30cc0 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
30cd0 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
30ce0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
30cf0 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
30d00 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
30d10 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
30d20 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
30d30 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
30d40 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
30d50 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
30d60 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
30d70 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
30d80 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
30d90 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
30da0 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
30db0 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
30dc0 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
30dd0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
30de0 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  /.  /* Outputs *
30df0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
30e00 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
30e10 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
30e20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
30e30 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
30e40 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
30e50 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
30e60 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
30e70 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
30e80 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
30e90 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
30ea0 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
30eb0 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  nt */.  } *aCons
30ec0 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69  traintUsage;.  i
30ed0 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
30ee0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
30ef0 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
30f00 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
30f10 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72  /.  char *idxStr
30f20 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
30f30 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62  * String, possib
30f40 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
30f50 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20   sqlite3_malloc 
30f60 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46  */.  int needToF
30f70 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
30f80 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
30f90 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
30fa0 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20  e() if true */. 
30fb0 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73   int orderByCons
30fc0 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54  umed;       /* T
30fd0 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73  rue if output is
30fe0 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64   already ordered
30ff0 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74   */.  double est
31000 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
31010 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
31020 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
31030 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65   index */.};.#de
31040 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
31050 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
31060 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
31070 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
31080 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
31090 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
310a0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
310b0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
310c0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
310d0 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
310e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
310f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
31100 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
31110 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
31120 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
31130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31140 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
31150 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
31160 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 45 58 50 45  entation.** EXPE
31170 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e  RIMENTAL.**.** ^
31180 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
31190 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
311a0 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ter a new [virtu
311b0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
311c0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c   name..** ^Modul
311d0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
311e0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
311f0 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
31200 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
31210 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
31220 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20  dule and before 
31230 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
31240 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
31250 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
31260 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  odule..**.** ^Th
31270 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
31280 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
31290 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
312a0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
312b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
312c0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  st parameter.  ^
312d0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
312e0 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
312f0 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
31300 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
31310 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
31320 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
31330 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
31340 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
31350 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
31360 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66  odule].   ^The f
31370 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
31380 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
31390 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
313a0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
313b0 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
313c0 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
313d0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
313e0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
313f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
31400 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
31410 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
31420 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
31430 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
31440 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ialized..**.** ^
31450 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
31460 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69  te_module_v2() i
31470 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66  nterface has a f
31480 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77  ifth parameter w
31490 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
314a0 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
314b0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c  ctor for the pCl
314c0 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69  ientData.  ^SQLi
314d0 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
314e0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
314f0 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
31500 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
31510 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
31520 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
31530 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
31540 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c 69  nter.  ^The sqli
31550 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
31560 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
31570 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
31580 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31590 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74  _module_v2() wit
315a0 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74  h a NULL.** dest
315b0 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54  ructor..*/.SQLIT
315c0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
315d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
315e0 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
315f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
31600 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
31610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
31620 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
31630 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
31640 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
31650 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
31660 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
31670 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
31680 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
31690 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
316a0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
316b0 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
316c0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
316d0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
316e0 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 53 51  Connect */.);.SQ
316f0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
31700 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  L int sqlite3_cr
31710 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a  eate_module_v2(.
31720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
31730 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31740 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
31750 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
31760 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
31770 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
31780 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
31790 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
317a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
317b0 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
317c0 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
317d0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
317e0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
317f0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69  ,         /* Cli
31800 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
31810 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
31820 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
31830 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a  y)(void*)     /*
31840 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74   Module destruct
31850 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29  or function */.)
31860 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31870 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
31880 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74   Instance Object
31890 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
318a0 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58  lite3_vtab.** EX
318b0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
318c0 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
318d0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
318e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
318f0 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20  s a subclass.** 
31900 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74  of this object t
31910 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
31920 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
31930 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74  .** of the [virt
31940 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63  ual table].  Eac
31950 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
31960 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74  ** be tailored t
31970 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
31980 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
31990 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
319a0 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73  n..** The purpos
319b0 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
319c0 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
319d0 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
319e0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d   that are.** com
319f0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  mon to all modul
31a00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31a10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61  s..**.** ^Virtua
31a20 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
31a30 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
31a40 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
31a50 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
31a60 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
31a70 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
31a80 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e  f()] to zErrMsg.
31a90 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
31aa0 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
31ab0 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
31ac0 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
31ad0 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
31ae0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
31af0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
31b00 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
31b10 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41   to zErrMsg.  ^A
31b20 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
31b30 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c  essage.** is del
31b40 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65  ivered up to the
31b50 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
31b60 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20  ion, the string 
31b70 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
31b80 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62  cally.** freed b
31b90 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  y sqlite3_free()
31ba0 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67   and the zErrMsg
31bb0 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a   field will be z
31bc0 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74  eroed..*/.struct
31bd0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a   sqlite3_vtab {.
31be0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
31bf0 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b  module *pModule;
31c00 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20    /* The module 
31c10 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c  for this virtual
31c20 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20   table */.  int 
31c30 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20  nRef;           
31c40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
31c50 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f  O LONGER USED */
31c60 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  .  char *zErrMsg
31c70 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
31c80 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73     /* Error mess
31c90 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  age from sqlite3
31ca0 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20  _mprintf() */.  
31cb0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
31cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
31cd0 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
31ce0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
31cf0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
31d00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
31d10 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f  tual Table Curso
31d20 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  r Object.** KEYW
31d30 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
31d40 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75  ab_cursor {virtu
31d50 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d  al table cursor}
31d60 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
31d70 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69  .**.** Every [vi
31d80 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
31d90 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  le] implementati
31da0 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
31db0 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c  ss of the.** fol
31dc0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
31dd0 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72   to describe cur
31de0 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20  sors that point 
31df0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72  into the.** [vir
31e00 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20  tual table] and 
31e10 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c  are used.** to l
31e20 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20  oop through the 
31e30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
31e40 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61  Cursors are crea
31e50 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ted using the.**
31e60 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65   [sqlite3_module
31e70 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20  .xOpen | xOpen] 
31e80 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f  method of the mo
31e90 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73  dule and are des
31ea0 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65  troyed.** by the
31eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65   [sqlite3_module
31ec0 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65  .xClose | xClose
31ed0 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f  ] method.  Curso
31ee0 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62  rs are used.** b
31ef0 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c  y the [xFilter],
31f00 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d   [xNext], [xEof]
31f10 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64  , [xColumn], and
31f20 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64   [xRowid] method
31f30 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75  s.** of the modu
31f40 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  le.  Each module
31f50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31f60 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74  will define.** t
31f70 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20  he content of a 
31f80 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65  cursor structure
31f90 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e   to suit its own
31fa0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
31fb0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78  is superclass ex
31fc0 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ists in order to
31fd0 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f   define fields o
31fe0 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61  f the cursor tha
31ff0 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20  t.** are common 
32000 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  to all implement
32010 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63  ations..*/.struc
32020 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
32030 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65  ursor {.  sqlite
32040 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20  3_vtab *pVtab;  
32050 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74      /* Virtual t
32060 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72  able of this cur
32070 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  sor */.  /* Virt
32080 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
32090 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
320a0 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
320b0 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
320c0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
320d0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68  3REF: Declare Th
320e0 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69  e Schema Of A Vi
320f0 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 20 45  rtual Table.** E
32100 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
32110 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d  * ^The [xCreate]
32120 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
32130 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20  methods of a.** 
32140 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
32150 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73  odule] call this
32160 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
32170 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
32180 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
32190 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
321a0 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
321b0 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
321c0 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
321d0 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ment..*/.SQLITE_
321e0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
321f0 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
32200 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
32210 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
32220 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32230 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
32240 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
32250 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 20 45  rtual Table.** E
32260 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
32270 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c  * ^(Virtual tabl
32280 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
32290 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
322a0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
322b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
322c0 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
322d0 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
322e0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
322f0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
32300 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
32310 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
32320 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
32330 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
32340 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29   be overloaded.)
32350 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41  ^.**.** ^(This A
32360 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
32370 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
32380 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
32390 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
323a0 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
323b0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
323c0 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
323d0 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
323e0 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
323f0 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
32400 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
32410 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20   is created.)^  
32420 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
32430 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
32440 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
32450 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
32460 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
32470 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
32480 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
32490 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
324a0 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
324b0 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
324c0 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
324d0 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63  placeholder func
324e0 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
324f0 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
32500 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  y a [virtual tab
32510 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  le]..*/.SQLITE_E
32520 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
32530 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
32540 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
32550 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
32560 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
32570 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
32580 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
32590 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
325a0 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
325b0 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
325c0 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
325d0 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
325e0 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
325f0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
32600 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
32610 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
32620 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
32630 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
32640 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
32650 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
32660 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
32670 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
32680 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
32690 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
326a0 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
326b0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
326c0 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
326d0 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
326e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
326f0 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
32700 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
32710 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
32720 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
32730 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
32740 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
32750 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
32760 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
32770 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
32780 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
32790 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20  An Open BLOB.** 
327a0 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
327b0 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
327c0 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
327d0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
327e0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
327f0 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
32800 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
32810 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
32820 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
32830 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
32840 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a  rformed..** ^Obj
32850 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
32860 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
32870 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
32880 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
32890 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
328a0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
328b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  ]..** ^The [sqli
328c0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
328d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
328e0 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
328f0 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
32900 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
32910 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
32920 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
32930 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  BLOB..** ^The [s
32940 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
32950 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  s()] interface r
32960 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
32970 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62  of the BLOB in b
32980 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
32990 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
329a0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
329b0 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
329c0 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
329d0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
329e0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  I/O.**.** ^(This
329f0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e   interfaces open
32a00 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s a [BLOB handle
32a10 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68   | handle] to th
32a20 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a  e BLOB located.*
32a30 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63  * in row iRow, c
32a40 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74  olumn zColumn, t
32a50 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64  able zTable in d
32a60 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20  atabase zDb;.** 
32a70 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
32a80 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68  the same BLOB th
32a90 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
32aa0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
32ab0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
32ac0 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
32ad0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
32ae0 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b   [rowid] = iRow;
32af0 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
32b00 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73  ** ^If the flags
32b10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
32b20 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
32b30 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
32b40 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20  for read.** and 
32b50 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49  write access. ^I
32b60 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
32b70 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
32b80 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
32b90 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20  ..** ^It is not 
32ba0 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
32bb0 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
32bc0 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64  s part of an ind
32bd0 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a  ex or primary .*
32be0 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e  * key for writin
32bf0 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20  g. ^If [foreign 
32c00 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
32c10 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74   are enabled, it
32c20 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73   is .** not poss
32c30 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
32c40 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
32c50 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b  rt of a [child k
32c60 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  ey] for writing.
32c70 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
32c80 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
32c90 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
32ca0 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
32cb0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
32cc0 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
32cd0 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
32ce0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
32cf0 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61  se that.** appea
32d00 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20  rs after the AS 
32d10 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65  keyword when the
32d20 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e   database is con
32d30 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54  nected using [AT
32d40 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74  TACH]..** ^For t
32d50 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
32d60 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62   file, the datab
32d70 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69  ase name is "mai
32d80 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50  n"..** ^For TEMP
32d90 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74   tables, the dat
32da0 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74  abase name is "t
32db0 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  emp"..**.** ^(On
32dc0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
32dd0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
32de0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42  d and the new [B
32df0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  LOB handle] is w
32e00 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70  ritten.** to *pp
32e10 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20  Blob. Otherwise 
32e20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
32e30 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
32e40 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a  *ppBlob is set.*
32e50 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70  * to be a null p
32e60 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68  ointer.)^.** ^Th
32e70 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
32e80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32e90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
32ea0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
32eb0 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
32ec0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
32ed0 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
32ee0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
32ef0 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
32f00 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74  nctions. ^Note t
32f10 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
32f20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
32f30 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
32f40 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
32f50 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
32f60 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
32f70 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
32f80 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
32f90 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
32fa0 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
32fb0 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
32fc0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  e..**.** ^(If th
32fd0 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f  e row that a BLO
32fe0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20  B handle points 
32ff0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62  to is modified b
33000 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  y an.** [UPDATE]
33010 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62  , [DELETE], or b
33020 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  y [ON CONFLICT] 
33030 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20  side-effects.** 
33040 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61  then the BLOB ha
33050 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61  ndle is marked a
33060 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20  s "expired"..** 
33070 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20  This is true if 
33080 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  any column of th
33090 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64  e row is changed
330a0 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a  , even a column.
330b0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  ** other than th
330c0 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68  e one the BLOB h
330d0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e  andle is open on
330e0 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .)^.** ^Calls to
330f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
33100 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
33110 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
33120 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72  ] for.** a expir
33130 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66  ed BLOB handle f
33140 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75  ail with an retu
33150 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
33160 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28  TE_ABORT]..** ^(
33170 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20  Changes written 
33180 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f  into a BLOB prio
33190 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78  r to the BLOB ex
331a0 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a  piring are not.*
331b0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  * rolled back by
331c0 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
331d0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
331e0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
331f0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
33200 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
33210 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
33220 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
33230 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68  )^.**.** ^Use th
33240 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
33250 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
33260 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
33270 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
33280 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
33290 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20   ^The size of a 
332a0 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
332b0 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
332c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
332d0 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
332e0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
332f0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
33300 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
33310 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
33320 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
33330 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
33340 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
33350 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
33360 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
33370 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
33380 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
33390 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
333a0 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
333b0 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
333c0 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
333d0 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
333e0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
333f0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
33400 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
33410 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
33420 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
33430 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
33440 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
33450 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
33460 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
33470 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69  b_close()]..*/.i
33480 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33490 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
334a0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
334b0 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
334c0 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
334d0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
334e0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
334f0 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
33500 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
33510 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
33520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33530 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
33540 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
33550 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
33560 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
33570 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
33580 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
33590 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
335a0 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
335b0 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
335c0 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
335d0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
335e0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
335f0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
33600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
33610 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
33620 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
33630 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
33640 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
33650 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
33660 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
33670 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
33680 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
33690 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
336a0 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
336b0 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
336c0 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
336d0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
336e0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
336f0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
33700 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
33710 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
33720 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
33730 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
33740 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
33750 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
33760 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
33770 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
33780 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
33790 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
337a0 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
337b0 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
337c0 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
337d0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
337e0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
337f0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
33800 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
33810 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
33820 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
33830 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
33840 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
33850 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
33860 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33870 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
33880 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33890 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
338a0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
338b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
338c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
338d0 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
338e0 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
338f0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
33900 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
33910 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
33920 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
33930 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
33940 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
33950 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
33960 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
33970 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
33980 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
33990 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
339a0 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
339b0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
339c0 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
339d0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
339e0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
339f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33a00 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33a10 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33a20 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33a30 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
33a40 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
33a50 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33a60 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
33a70 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
33a80 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
33a90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33aa0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
33ab0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33ac0 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33ad0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33ae0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33af0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33b00 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33b10 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
33b20 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
33b30 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
33b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33b50 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
33b60 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
33b70 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
33b80 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
33b90 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
33ba0 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
33bb0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
33bc0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
33bd0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
33be0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
33bf0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
33c00 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
33c10 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
33c20 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
33c30 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
33c40 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
33c50 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
33c60 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
33c70 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
33c80 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
33c90 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
33ca0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
33cb0 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
33cc0 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
33cd0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
33ce0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
33cf0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
33d00 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
33d10 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
33d20 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
33d30 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
33d40 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
33d50 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
33d60 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
33d70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
33d80 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
33d90 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
33da0 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
33db0 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
33dc0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
33dd0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
33de0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
33df0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
33e00 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
33e10 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
33e20 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
33e30 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
33e40 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
33e50 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
33e60 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
33e70 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
33e80 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
33e90 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
33ea0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
33eb0 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
33ec0 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
33ed0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
33ee0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33ef0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
33f00 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
33f10 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
33f20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
33f30 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
33f40 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
33f50 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
33f60 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
33f70 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
33f80 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
33f90 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
33fa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
33fb0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
33fc0 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
33fd0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
33fe0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
33ff0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
34000 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
34010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34020 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
34030 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
34040 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
34050 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
34060 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
34070 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
34080 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
34090 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
340a0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
340b0 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
340c0 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
340d0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
340e0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
340f0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
34100 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
34110 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
34120 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
34130 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
34140 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
34150 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
34160 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
34170 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
34180 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
34190 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
341a0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
341b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
341c0 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
341d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
341e0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
341f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
34200 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73   the BLOB; it is
34210 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
34220 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
34230 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20   size of a BLOB 
34240 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a  using this API..
34250 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
34260 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
34270 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
34280 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
34290 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
342a0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
342b0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
342c0 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20  s written.  ^If 
342d0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
342e0 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
342f0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
34300 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
34310 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
34320 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
34330 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
34340 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
34350 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
34360 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
34370 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
34380 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34390 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
343a0 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
343b0 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
343c0 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
343d0 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
343e0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
343f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
34400 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20  T].  ^Writes to 
34410 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63  the BLOB that oc
34420 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65  curred.** before
34430 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
34440 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e  e] expired are n
34450 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ot rolled back b
34460 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74  y the.** expirat
34470 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c  ion of the handl
34480 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  e, though of cou
34490 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65  rse those change
344a0 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20  s might.** have 
344b0 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e  been overwritten
344c0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
344d0 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74  t that expired t
344e0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a  he BLOB handle.*
344f0 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e  * or by other in
34500 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d  dependent statem
34510 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ents..**.** ^(On
34520 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
34530 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72  3_blob_write() r
34540 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
34550 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
34560 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
34570 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34580 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34590 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
345a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
345b0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
345c0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
345d0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
345e0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
345f0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34600 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34610 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34620 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34630 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34640 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34650 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
34660 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
34670 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
34680 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34690 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
346a0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
346b0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
346c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
346d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
346e0 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ad()]..*/.int sq
346f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
34700 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
34710 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
34720 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
34730 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
34740 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
34750 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
34760 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
34770 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
34780 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
34790 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
347a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
347b0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
347c0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
347d0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
347e0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
347f0 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
34800 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
34810 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
34820 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
34830 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
34840 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
34850 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
34860 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
34870 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
34880 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
34890 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
348a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
348b0 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rovided..**.** ^
348c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
348d0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
348e0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
348f0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
34900 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  n its name..** ^
34910 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
34920 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61  ensitive..** ^Na
34930 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
34940 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
34950 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  rings..** ^If th
34960 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
34970 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34980 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
34990 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20  ^If zVfsName is 
349a0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
349b0 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74  fault VFS is ret
349c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65  urned..**.** ^Ne
349d0 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
349e0 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
349f0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
34a00 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77  ()..** ^Each new
34a10 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
34a20 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
34a30 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34a40 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  g is set..** ^Th
34a50 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
34a60 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
34a70 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
34a80 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e  out injury..** ^
34a90 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
34aa0 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
34ab0 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
34ac0 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
34ad0 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
34ae0 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
34af0 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
34b00 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
34b10 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
34b20 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
34b30 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
34b40 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
34b50 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
34b60 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
34b70 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
34b80 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
34b90 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
34ba0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
34bb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69  d..**.** ^Unregi
34bc0 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
34bd0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
34be0 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
34bf0 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20  erface..** ^(If 
34c00 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
34c10 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
34c20 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
34c30 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
34c40 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
34c50 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
34c60 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
34c70 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ry.)^.*/.sqlite3
34c80 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
34c90 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
34ca0 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
34cb0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
34cc0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
34cd0 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
34ce0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
34cf0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
34d00 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
34d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34d20 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
34d30 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
34d40 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
34d50 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
34d60 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
34d70 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
34d80 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
34d90 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
34da0 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
34db0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
34dc0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
34dd0 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
34de0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
34df0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
34e00 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
34e10 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
34e20 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
34e30 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ons.** of these 
34e40 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20  mutex routines. 
34e50 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   An appropriate 
34e60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
34e70 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75  * is selected au
34e80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63  tomatically at c
34e90 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28  ompile-time.  ^(
34ea0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
34eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34ec0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
34ed0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
34ee0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
34ef0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
34f00 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
34f10 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
34f20 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
34f30 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
34f40 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
34f50 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
34f60 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
34f70 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
34f80 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
34f90 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
34fa0 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
34fb0 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
34fc0 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
34fd0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
34fe0 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
34ff0 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
35000 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51  cation.  ^The SQ
35010 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
35020 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
35030 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
35040 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
35050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
35060 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
35070 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32   for use on OS/2
35080 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64  , Unix, and Wind
35090 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ows..**.** ^(If 
350a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
350b0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
350c0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
350d0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
350e0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
350f0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
35100 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
35110 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
35120 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35130 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
35140 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
35150 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
35160 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
35170 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
35180 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
35190 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
351a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
351b0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
351c0 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
351d0 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
351e0 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
351f0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
35200 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
35210 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
35220 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
35230 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
35240 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
35250 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
35260 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
35270 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
35280 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
35290 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
352a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
352b0 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75   it. ^If it retu
352c0 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
352d0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
352e0 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
352f0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51   allocated.  ^SQ
35300 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
35310 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
35320 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
35330 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  r.  ^(The argume
35340 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
35350 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
35360 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
35370 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
35380 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35390 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
353a0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
353b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
353c0 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
353d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
353e0 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
353f0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
35400 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
35410 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35420 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
35430 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35440 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
35450 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35460 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
35470 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
35480 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
35490 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  RU2.** </ul>)^.*
354a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
354b0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53  two constants (S
354c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
354d0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
354e0 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20  X_RECURSIVE).** 
354f0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
35500 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
35510 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
35520 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20  utex.  ^The new 
35530 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
35540 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
35550 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
35560 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
35570 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
35580 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
35590 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
355a0 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
355b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
355c0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
355d0 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
355e0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
355f0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
35600 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
35610 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
35620 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
35630 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  to.  ^SQLite wil
35640 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
35650 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
35660 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
35670 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
35680 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66  ds one.  ^If a f
35690 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
356a0 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
356b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
356c0 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
356d0 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
356e0 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
356f0 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
35700 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
35710 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
35720 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
35730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68  ..**.** ^The oth
35740 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
35750 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
35760 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28  _mutex_alloc() (
35770 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a  anything other.*
35780 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55  * than SQLITE_MU
35790 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
357a0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
357b0 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e  IVE) each return
357c0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
357d0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
357e0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53  sting mutex.  ^S
357f0 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
35800 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
35810 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
35820 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
35830 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
35840 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
35850 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
35860 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
35870 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
35880 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
35890 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
358a0 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
358b0 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
358c0 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
358d0 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
358e0 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
358f0 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
35900 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
35910 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
35920 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35930 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
35940 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
35950 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
35960 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
35970 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
35980 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
35990 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
359a0 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
359b0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
359c0 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
359d0 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
359e0 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20  ery call.  ^But 
359f0 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
35a00 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
35a10 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
35a20 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
35a30 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
35a40 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
35a50 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
35a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
35a70 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
35a80 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
35a90 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
35aa0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
35ab0 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20  mutex.  ^SQLite 
35ac0 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
35ad0 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
35ae0 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
35af0 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
35b00 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
35b10 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
35b20 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
35b30 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
35b40 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
35b50 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
35b60 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
35b70 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
35b80 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
35b90 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76  or.  ^SQLite nev
35ba0 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
35bb0 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
35bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35bd0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35be0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
35bf0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
35c00 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
35c10 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
35c20 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68    ^If another th
35c30 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
35c40 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
35c50 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
35c60 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
35c70 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
35c80 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
35c90 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
35ca0 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20  ITE_BUSY.  ^The 
35cb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
35cc0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
35cd0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
35ce0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
35cf0 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d  sful entry.  ^(M
35d00 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
35d10 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
35d20 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
35d30 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
35d40 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
35d50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
35d60 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65  .** In such case
35d70 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
35d80 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
35d90 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
35da0 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
35db0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
35dc0 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e   can enter.)^  ^
35dd0 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72  (If the same thr
35de0 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
35df0 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  er any other.** 
35e00 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f  kind of mutex mo
35e10 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
35e20 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
35e30 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69  defined..** SQLi
35e40 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
35e50 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
35e60 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
35e70 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
35e80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65  .)^.**.** ^(Some
35e90 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
35ea0 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
35eb0 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
35ec0 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
35ed0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
35ee0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
35ef0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
35f00 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
35f10 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
35f20 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
35f30 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
35f40 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
35f50 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
35f60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
35f70 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
35f80 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
35f90 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
35fa0 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a   behavior.)^.**.
35fb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35fc0 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
35fd0 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
35fe0 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
35ff0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
36000 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
36010 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62  hread.   ^(The b
36020 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
36030 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
36040 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
36050 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
36060 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
36070 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
36080 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
36090 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
360a0 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
360b0 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ither.)^.**.** ^
360c0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
360d0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
360e0 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
360f0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
36100 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
36110 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
36120 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
36130 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
36140 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
36150 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
36160 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36170 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
36180 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
36190 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
361a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
361b0 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
361c0 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
361d0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
361e0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
361f0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
36200 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
36210 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
36220 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
36230 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
36240 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
36250 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
36260 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36280 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
36290 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49  Object.** EXPERI
362a0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
362b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
362c0 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
362d0 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
362e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
362f0 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
36300 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
36310 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
36320 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
36330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36340 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
36350 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
36360 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
36370 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
36380 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
36390 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
363a0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
363b0 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
363c0 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
363d0 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
363e0 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
363f0 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
36400 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
36410 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
36420 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
36430 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
36440 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
36450 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
36460 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
36470 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
36480 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
36490 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
364a0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
364b0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
364c0 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
364d0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
364e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
364f0 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
36500 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
36510 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
36520 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
36530 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
36540 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
36550 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
36560 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
36570 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  n..**.** ^The xM
36580 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
36590 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
365a0 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
365b0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
365c0 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
365d0 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
365e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
365f0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
36600 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69  * ^The xMutexIni
36610 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  t routine is cal
36620 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61  le by SQLite exa
36630 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
36640 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
36650 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36660 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
36670 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
36680 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69  xEnd method defi
36690 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
366a0 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
366b0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
366c0 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62  ystem shutdown b
366d0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  y the sqlite3_sh
366e0 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f  utdown() functio
366f0 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  n. The.** implem
36700 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73  entation of this
36710 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63   method is expec
36720 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61  ted to release a
36730 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  ll outstanding.*
36740 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61  * resources obta
36750 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65  ined by the mute
36760 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d  x methods implem
36770 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69  entation, especi
36780 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62  ally.** those ob
36790 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d  tained by the xM
367a0 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e  utexInit method.
367b0 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64    ^The xMutexEnd
367c0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
367d0 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  is invoked exact
367e0 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
367f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36800 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
36810 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69  *.** ^(The remai
36820 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f  ning seven metho
36830 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  ds defined by th
36840 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d  is structure (xM
36850 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d  utexAlloc,.** xM
36860 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78  utexFree, xMutex
36870 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79  Enter, xMutexTry
36880 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78  , xMutexLeave, x
36890 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a  MutexHeld and.**
368a0 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20   xMutexNotheld) 
368b0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f  implement the fo
368c0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
368d0 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79  es (respectively
368e0 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ):.**.** <ul>.**
368f0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36900 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
36910 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36920 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
36930 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _free()] </li>.*
36940 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36950 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36960 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
36970 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36980 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  x_try()] </li>.*
36990 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
369a0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
369b0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
369c0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
369d0 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  x_held()] </li>.
369e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
369f0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
36a00 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  d()] </li>.** </
36a10 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
36a20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
36a30 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
36a40 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
36a50 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
36a60 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
36a70 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
36a80 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
36a90 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
36aa0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
36ab0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36ac0 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
36ad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
36ae0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
36af0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
36b00 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
36b10 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
36b20 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
36b30 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
36b40 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
36b50 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
36b60 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36b70 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
36b80 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
36b90 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
36ba0 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
36bb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
36bc0 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
36bd0 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
36be0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
36bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
36c00 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
36c10 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
36c20 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20  e.  ^It must be 
36c30 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69  harmless to.** i
36c40 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74  nvoke xMutexInit
36c50 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73  () mutiple times
36c60 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
36c70 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74   process and wit
36c80 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e  hout.** interven
36c90 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75  ing calls to xMu
36ca0 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e  texEnd().  Secon
36cb0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
36cc0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75   calls to.** xMu
36cd0 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62  texInit() must b
36ce0 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  e no-ops..**.** 
36cf0 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75  ^xMutexInit() mu
36d00 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
36d10 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
36d20 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
36d30 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
36d40 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
36d50 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75   ^Similarly, xMu
36d60 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
36d70 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
36d80 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
36d90 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
36da0 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65   mutex.  ^Howeve
36db0 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
36dc0 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
36dd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
36de0 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
36df0 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
36e00 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  x..**.** ^SQLite
36e10 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
36e20 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
36e30 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
36e40 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
36e50 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
36e60 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
36e70 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
36e80 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
36e90 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
36ea0 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
36eb0 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
36ec0 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
36ed0 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
36ee0 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
36ef0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
36f00 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
36f10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
36f20 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
36f30 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
36f40 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
36f50 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
36f60 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
36f70 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
36f80 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
36f90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
36fa0 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
36fb0 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
36fc0 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
36fd0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
36fe0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
36ff0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37000 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
37010 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
37020 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
37030 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
37040 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
37050 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
37060 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
37070 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37080 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
37090 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
370a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
370b0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
370c0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
370d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
370e0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
370f0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
37100 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
37110 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
37120 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
37130 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
37140 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c  ments.  ^The SQL
37150 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
37160 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
37170 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
37180 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
37190 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
371a0 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
371b0 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
371c0 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
371d0 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72   ^The SQLite cor
371e0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
371f0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
37200 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
37210 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
37220 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
37230 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
37240 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72  UG flag.  ^Exter
37250 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
37260 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
37270 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
37280 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
37290 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
372a0 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
372b0 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
372c0 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
372d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
372e0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
372f0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
37300 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
37310 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
37320 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
37330 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
37340 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
37350 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
37360 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
37370 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
37380 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
37390 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
373a0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
373b0 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
373c0 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
373d0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
373e0 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
373f0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
37400 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
37410 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
37420 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
37430 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
37440 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
37450 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
37460 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
37470 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
37480 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37490 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
374a0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
374b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
374c0 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
374d0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
374e0 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73  turn 1.   This s
374f0 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
37500 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
37510 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
37520 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
37530 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
37540 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
37550 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
37560 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
37570 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
37580 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
37590 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
375a0 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
375b0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
375c0 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
375d0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
375e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
375f0 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
37600 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
37610 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
37620 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
37630 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  o do.  ^The sqli
37640 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
37650 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
37660 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
37670 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
37680 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37690 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42  .*/.#ifndef NDEB
376a0 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  UG.int sqlite3_m
376b0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
376c0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
376d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
376e0 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
376f0 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ex*);.#endif../*
37700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
37710 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20  tex Types.**.** 
37720 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  The [sqlite3_mut
37730 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65  ex_alloc()] inte
37740 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69  rface takes a si
37750 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
37760 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66   which is one of
37770 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
37780 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
37790 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69  The set of stati
377a0 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68  c mutexes may ch
377b0 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51  ange from one SQ
377c0 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20  Lite release to 
377d0 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
377e0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
377f0 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69  override the bui
37800 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69  lt-in mutex logi
37810 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65  c must be.** pre
37820 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f  pared to accommo
37830 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  date additional 
37840 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a  static mutexes..
37850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37860 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20  E_MUTEX_FAST    
37870 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
37880 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37890 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
378a0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
378b0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
378c0 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69  ASTER    2.#defi
378d0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
378e0 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20  STATIC_MEM      
378f0 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   3  /* sqlite3_m
37900 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69  alloc() */.#defi
37910 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37920 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20  STATIC_MEM2     
37930 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20   4  /* NOT USED 
37940 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37950 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f  E_MUTEX_STATIC_O
37960 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73  PEN      4  /* s
37970 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28  qlite3BtreeOpen(
37980 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37990 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
379a0 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
379b0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
379c0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
379d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
379e0 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
379f0 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
37a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37a10 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
37a20 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72  U2      7  /* lr
37a30 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a  u page list */..
37a40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37a50 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74  Retrieve the mut
37a60 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ex for a databas
37a70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e connection.**.
37a80 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
37a90 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37aa0 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65  nter the [sqlite
37ab0 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20  3_mutex] object 
37ac0 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69  that .** seriali
37ad0 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68  zes access to th
37ae0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37af0 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e  ection] given in
37b00 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
37b10 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61   when the [threa
37b20 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65  ding mode] is Se
37b30 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49 66  rialized..** ^If
37b40 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
37b50 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d  mode] is Single-
37b60 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d  thread or Multi-
37b70 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73  thread then this
37b80 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
37b90 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
37ba0 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  er..*/.sqlite3_m
37bb0 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62  utex *sqlite3_db
37bc0 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29  _mutex(sqlite3*)
37bd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37be0 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
37bf0 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
37c00 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Files.**.** ^Th
37c10 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
37c20 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
37c30 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
37c40 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
37c50 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
37c60 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
37c70 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
37c80 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
37c90 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
37ca0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
37cb0 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
37cc0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
37cd0 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 6e  ument. ^The.** n
37ce0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
37cf0 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20 74  ase "main" for t
37d00 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
37d10 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 74   or "temp" for t
37d20 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 62  he.** TEMP datab
37d30 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d 65  ase, or the name
37d40 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 66   that appears af
37d50 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
37d60 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  rd for.** databa
37d70 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 64  ses that are add
37d80 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 54  ed using the [AT
37d90 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  TACH] SQL comman
37da0 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 6f  d..** ^A NULL po
37db0 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 65  inter can be use
37dc0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  d in place of "m
37dd0 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 6f  ain" to refer to
37de0 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 74   the.** main dat
37df0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 5e  abase file..** ^
37e00 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
37e10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
37e20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
37e30 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
37e40 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
37e50 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
37e60 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
37e70 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
37e80 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
37e90 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61    ^The return va
37ea0 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65  lue of the xFile
37eb0 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f  Control.** metho
37ec0 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65  d becomes the re
37ed0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
37ee0 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
37ef0 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
37f00 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e   parameter (zDbN
37f10 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61  ame) does not ma
37f20 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  tch the name of 
37f30 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61  any.** open data
37f40 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20  base file, then 
37f50 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20  SQLITE_ERROR is 
37f60 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69 73  returned.  ^This
37f70 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
37f80 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64  s not remembered
37f90 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
37fa0 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71   recalled by [sq
37fb0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
37fc0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
37fd0 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 20  errmsg()].  The 
37fe0 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65  underlying xFile
37ff0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d  Control method m
38000 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74  ight.** also ret
38010 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  urn SQLITE_ERROR
38020 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77  .  There is no w
38030 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73  ay to distinguis
38040 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20  h between.** an 
38050 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d  incorrect zDbNam
38060 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f  e and an SQLITE_
38070 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f  ERROR return fro
38080 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  m the underlying
38090 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
380a0 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53   method..**.** S
380b0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
380c0 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
380d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
380e0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71  _file_control(sq
380f0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
38100 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74  ar *zDbName, int
38110 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   op, void*);../*
38120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
38130 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 0a  sting Interface.
38140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38150 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
38160 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
38170 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20  sed to read out 
38180 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74  internal.** stat
38190 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20  e of SQLite and 
381a0 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73  to inject faults
381b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72   into SQLite for
381c0 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70   testing.** purp
381d0 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72 73  oses.  ^The firs
381e0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
381f0 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  n operation code
38200 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
38210 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20  .** the number, 
38220 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65  meaning, and ope
38230 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75  ration of all su
38240 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
38250 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ers..**.** This 
38260 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
38270 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c   for use by appl
38280 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78  ications.  It ex
38290 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66  ists solely.** f
382a0 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65  or verifying the
382b0 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69   correct operati
382c0 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
382d0 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e   library.  Depen
382e0 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74  ding.** on how t
382f0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
38300 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74  y is compiled, t
38310 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69  his interface mi
38320 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a  ght not exist..*
38330 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
38340 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f   of the operatio
38350 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d  n codes, their m
38360 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72  eanings, the par
38370 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20  ameters.** they 
38380 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74  take, and what t
38390 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73  hey do are all s
383a0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
383b0 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
383c0 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20  .** Unlike most 
383d0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50  of the SQLite AP
383e0 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  I, this function
383f0 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
38400 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65  ed to.** operate
38410 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72   consistently fr
38420 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
38430 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69  o the next..*/.i
38440 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  nt sqlite3_test_
38450 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20  control(int op, 
38460 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
38470 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49  I3REF: Testing I
38480 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69  nterface Operati
38490 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
384a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
384b0 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65  re the valid ope
384c0 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61  ration code para
384d0 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61  meters used.** a
384e0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
384f0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
38500 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _test_control()]
38510 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61  ..**.** These pa
38520 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65  rameters and the
38530 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20  ir meanings are 
38540 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
38550 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74  e.** without not
38560 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75  ice.  These valu
38570 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69  es are for testi
38580 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79  ng purposes only
38590 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
385a0 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  s should not use
385b0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61   any of these pa
385c0 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a  rameters or the.
385d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74  ** [sqlite3_test
385e0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
385f0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
38600 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
38610 4c 5f 46 49 52 53 54 20 20 20 20 20 20 20 20 20  L_FIRST         
38620 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
38630 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
38640 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20  CTRL_PRNG_SAVE  
38650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
38660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
38670 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53  ESTCTRL_PRNG_RES
38680 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20  TORE            
38690 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
386a0 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f  E_TESTCTRL_PRNG_
386b0 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20  RESET           
386c0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
386d0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49  LITE_TESTCTRL_BI
386e0 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20  TVEC_TEST       
386f0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
38700 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38710 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20  _FAULT_INSTALL  
38720 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
38730 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
38740 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f  TRL_BENIGN_MALLO
38750 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23  C_HOOKS     10.#
38760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
38770 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42  STCTRL_PENDING_B
38780 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31  YTE            1
38790 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
387a0 5f 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54  _TESTCTRL_ASSERT
387b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
387c0 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
387d0 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57  ITE_TESTCTRL_ALW
387e0 41 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20  AYS             
387f0 20 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20       13.#define 
38800 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
38810 52 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20  RESERVE         
38820 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
38830 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
38840 52 4c 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 53  RL_OPTIMIZATIONS
38850 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
38860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
38870 54 43 54 52 4c 5f 49 53 4b 45 59 57 4f 52 44 20  TCTRL_ISKEYWORD 
38880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 36                16
38890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
388a0 54 45 53 54 43 54 52 4c 5f 4c 41 53 54 20 20 20  TESTCTRL_LAST   
388b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
388c0 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   16../*.** CAPI3
388d0 52 45 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74  REF: SQLite Runt
388e0 69 6d 65 20 53 74 61 74 75 73 0a 2a 2a 20 45 58  ime Status.** EX
388f0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
38900 20 5e 54 68 6