/ Hex Artifact Content
Login

Artifact c5001b77dc0cb046136da65d8dbdf234048be21d:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90d0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
90e0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
90f0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9100: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
9110: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
9120: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
9130: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
9140: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
9150: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
9160: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
9170: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
9180: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
9190: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
91a0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
91b0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
91c0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
91d0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
91e0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
91f0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
9200: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
9210: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
9220: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
9230: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
9240: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
9250: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
9260: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9270: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
9280: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
9290: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
92a0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
92b0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
92c0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
92d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
92e0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
92f0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
9300: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
9310: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9320: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
9330: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
9340: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
9350: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
9360: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9370: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
9380: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
9390: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
93a0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
93b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
93c0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
93d0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
93e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
93f0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
9400: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
9410: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
9420: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
9430: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
9440: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
9450: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
9460: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
9470: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
9480: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
9490: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
94a0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
94b0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
94d0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
94e0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
94f0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
9500: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
9510: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
9520: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
9530: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
9540: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
9550: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
9560: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
9570: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
9580: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
9590: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
95a0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
95b0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
95c0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
95d0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
95e0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
95f0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9600: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
9610: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
9620: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9630: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9640: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
9650: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
9660: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
9670: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
9680: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
9690: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
96a0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
96b0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
96c0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
96d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
96e0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
96f0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9700: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
9710: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9720: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
9730: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9740: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9750: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
9760: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9770: 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20  itable..** With 
9780: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9790: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
97a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
97b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
97c0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a  e is readable..*
97d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
97e0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
97f0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
9800: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
9810: 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ITE 1.#define SQ
9820: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9830: 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43        2../*.** C
9840: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
9850: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
9860: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
9870: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9880: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9890: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
98a0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
98b0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
98c0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
98d0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
98e0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
98f0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
9900: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
9910: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
9920: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
9930: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
9940: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
9950: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
9960: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
9970: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
9980: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
9990: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
99a0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
99b0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
99c0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
99d0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
99e0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
99f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
9a00: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
9a10: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
9a20: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
9a30: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
9a40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9a50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
9a60: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
9a70: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
9a80: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
9a90: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
9aa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9ab0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
9ac0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
9ad0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
9ae0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
9af0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
9b00: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
9b10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
9b20: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
9b30: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
9b40: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
9b50: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
9b60: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
9b70: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9b80: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
9b90: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
9ba0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
9bb0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
9bc0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
9bd0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
9be0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9bf0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
9c00: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
9c10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9c20: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
9c30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
9c40: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
9c50: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
9c60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
9c70: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
9c80: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
9c90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9ca0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
9cb0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
9cc0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9cd0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
9ce0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
9cf0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
9d00: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
9d10: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
9d20: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
9d30: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
9d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
9d50: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
9d60: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
9d70: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
9d80: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
9d90: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
9da0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
9db0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
9dc0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
9dd0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
9de0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
9df0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
9e00: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
9e10: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
9e20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9e30: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
9e40: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
9e50: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
9e60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9e70: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9e80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
9e90: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
9ea0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
9eb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9ec0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
9ed0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
9ee0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
9ef0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
9f00: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
9f10: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
9f20: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
9f30: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
9f40: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
9f50: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
9f60: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
9f70: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9f80: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9f90: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
9fa0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
9fb0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
9fc0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
9fd0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
9fe0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
9ff0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
a000: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a010: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
a020: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
a030: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
a040: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
a050: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
a060: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a070: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
a080: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
a090: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
a0a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
a0b0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
a0c0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
a0d0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
a0e0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
a0f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a100: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
a110: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
a120: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
a130: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
a140: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
a150: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
a160: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
a170: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
a180: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
a190: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
a1a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
a1b0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
a1c0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a1d0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a1e0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
a1f0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
a200: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
a210: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
a220: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
a230: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
a240: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
a250: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
a260: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
a270: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
a280: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
a290: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
a2a0: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
a2b0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
a2c0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
a2d0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
a2e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a2f0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
a300: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
a310: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
a320: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
a330: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
a340: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
a350: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
a360: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a370: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
a380: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
a390: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
a3a0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
a3b0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
a3c0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
a3d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
a3e0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
a3f0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
a400: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
a410: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
a420: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
a430: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
a440: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
a450: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
a460: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
a470: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
a480: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
a490: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
a4a0: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
a4b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
a4c0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
a4d0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
a4e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
a4f0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
a500: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
a510: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
a520: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
a530: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
a540: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
a550: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
a560: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
a570: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
a580: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
a590: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
a5a0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
a5b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a5c0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
a5d0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
a5e0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
a5f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
a600: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a610: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
a620: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
a630: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
a640: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
a650: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
a660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
a670: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
a680: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
a690: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
a6a0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
a6b0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
a6c0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
a6d0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
a6e0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
a6f0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
a700: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
a710: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
a720: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a730: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a740: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a750: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a760: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a770: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a780: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a790: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a7a0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a7b0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a7c0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a7d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a7e0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a7f0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a800: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a810: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a820: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a830: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a840: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a850: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a860: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a870: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a880: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a890: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a8a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a8b0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a8c0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a8d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a8e0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a8f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
a900: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a910: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a920: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a930: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
a940: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a950: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
a960: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
a970: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
a980: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
a990: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a9a0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
a9b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
a9c0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
a9d0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
a9e0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
a9f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
aa00: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
aa10: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
aa20: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
aa30: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
aa40: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
aa50: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
aa60: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
aa70: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
aa80: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
aa90: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
aaa0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
aab0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
aac0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
aad0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
aae0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
aaf0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
ab00: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
ab10: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
ab20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ab30: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
ab40: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
ab50: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
ab60: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
ab70: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ab80: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
ab90: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
aba0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
abb0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
abc0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
abd0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
abe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
abf0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
ac00: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ac10: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
ac20: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
ac30: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
ac40: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
ac50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ac60: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
ac70: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
ac80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ac90: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
aca0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
acb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
acc0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
acd0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
ace0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
acf0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
ad00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ad10: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
ad20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
ad30: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
ad40: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
ad50: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
ad60: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
ad70: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
ad80: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
ad90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ada0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
adb0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
adc0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
add0: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
ade0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
adf0: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
ae00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ae10: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
ae20: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
ae30: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
ae40: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
ae50: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
ae60: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
ae70: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ae80: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
ae90: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
aea0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
aeb0: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
aec0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
aed0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
aee0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
aef0: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
af00: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
af10: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
af20: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
af30: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
af40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
af50: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
af60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
af70: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
af80: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
af90: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
afa0: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
afb0: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
afc0: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
afd0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
afe0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
aff0: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
b000: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
b010: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
b020: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
b030: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
b040: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
b050: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
b060: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
b070: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
b080: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
b090: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
b0a0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
b0b0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
b0c0: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
b0d0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
b0e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
b0f0: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
b100: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
b110: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
b120: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
b130: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
b140: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
b150: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
b160: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
b170: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
b180: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
b190: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
b1a0: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
b1b0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
b1c0: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
b1d0: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
b1e0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
b1f0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
b200: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
b210: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
b220: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
b230: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
b240: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
b250: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
b260: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
b270: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
b280: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
b290: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
b2a0: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
b2b0: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
b2c0: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
b2d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
b2e0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
b2f0: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
b300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b310: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
b320: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b330: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
b340: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
b350: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b360: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
b370: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
b380: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
b390: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
b3a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3b0: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b3c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
b3d0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
b3e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
b3f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b400: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
b410: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b420: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
b430: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
b440: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
b450: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
b460: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
b470: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b480: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
b490: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
b4a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b4b0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b4c0: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
b4d0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
b4e0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b4f0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
b500: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
b510: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b520: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
b530: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
b540: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
b550: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
b560: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
b570: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
b580: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
b590: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
b5a0: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
b5b0: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
b5c0: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
b5d0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
b5e0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
b5f0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
b600: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
b610: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
b620: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
b630: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
b640: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
b650: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
b660: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
b670: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
b680: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
b690: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b6a0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
b6b0: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
b6c0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
b6d0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
b6e0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
b6f0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
b700: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
b710: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
b720: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
b730: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
b740: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
b750: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
b760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
b770: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
b780: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
b790: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
b7a0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
b7b0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
b7c0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
b7d0: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
b7e0: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
b7f0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
b800: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
b810: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
b820: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
b830: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
b840: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
b850: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
b860: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
b870: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
b880: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
b890: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
b8a0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
b8b0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
b8c0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
b8d0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
b8e0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
b8f0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
b900: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
b910: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
b920: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
b930: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
b940: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
b950: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
b960: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
b970: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
b980: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
b990: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
b9a0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
b9b0: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
b9c0: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
b9d0: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
b9e0: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
b9f0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
ba00: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
ba10: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
ba20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ba30: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
ba40: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
ba50: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
ba60: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
ba70: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
ba80: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
ba90: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
baa0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
bab0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
bac0: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
bad0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
bae0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
baf0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
bb00: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
bb10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
bb20: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
bb30: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
bb40: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
bb50: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
bb60: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
bb70: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
bb80: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
bb90: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
bba0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
bbb0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
bbc0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
bbd0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
bbe0: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
bbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
bc00: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
bc10: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
bc20: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
bc30: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
bc40: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
bc50: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
bc60: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
bc70: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
bc80: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
bc90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bca0: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
bcb0: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
bcc0: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
bcd0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bce0: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
bcf0: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
bd00: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
bd10: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
bd20: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
bd30: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
bd40: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
bd50: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
bd60: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
bd70: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
bd80: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
bd90: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
bda0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
bdb0: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
bdc0: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
bdd0: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
bde0: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
bdf0: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
be00: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
be10: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
be20: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
be30: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
be40: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
be50: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
be60: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
be70: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
be80: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
be90: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
bea0: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
beb0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
bec0: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
bed0: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
bee0: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
bef0: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
bf00: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
bf10: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
bf20: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
bf30: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
bf40: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
bf50: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
bf60: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
bf70: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
bf80: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
bf90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bfa0: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
bfb0: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
bfc0: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
bfd0: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
bfe0: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
bff0: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
c000: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
c010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c020: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
c030: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
c040: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
c050: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
c060: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
c070: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
c080: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
c090: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
c0a0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
c0b0: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
c0c0: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
c0d0: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
c0e0: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
c0f0: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
c100: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c110: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c120: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
c130: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
c140: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c150: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
c160: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
c170: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
c180: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
c190: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
c1a0: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
c1b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
c1c0: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
c1d0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
c1e0: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
c1f0: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
c200: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
c210: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
c220: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
c230: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
c240: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
c250: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c260: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
c270: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
c280: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
c290: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
c2a0: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
c2b0: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
c2c0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c2d0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
c2e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c2f0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
c300: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
c310: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
c320: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
c330: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
c340: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
c350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
c360: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
c370: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
c380: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
c390: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c3a0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
c3b0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
c3c0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
c3d0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
c3e0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
c3f0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
c400: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
c410: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
c420: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
c430: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
c440: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
c450: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
c460: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
c470: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
c480: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
c490: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
c4a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c4b0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
c4c0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
c4d0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
c4e0: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
c4f0: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
c500: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c510: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
c520: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
c530: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
c540: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c550: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
c560: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
c570: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
c580: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
c590: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
c5a0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
c5b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
c5c0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
c5d0: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
c5e0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c5f0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
c600: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
c610: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
c620: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
c630: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
c640: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
c650: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
c660: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
c670: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
c680: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
c690: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
c6a0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
c6b0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
c6c0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
c6d0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
c6e0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
c6f0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
c700: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
c710: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
c720: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
c730: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
c740: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
c750: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
c760: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
c770: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
c780: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
c790: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
c7a0: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
c7b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
c7c0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
c7d0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
c7e0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
c7f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c800: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
c810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c820: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
c830: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c840: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
c850: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c860: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c870: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c880: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
c890: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
c8a0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
c8b0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
c8c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
c8d0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
c8e0: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
c8f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c900: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
c910: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
c920: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c930: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
c940: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
c950: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
c960: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c970: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
c980: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
c990: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
c9a0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
c9b0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
c9c0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
c9d0: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
c9e0: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
c9f0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
ca00: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
ca10: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
ca20: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
ca30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ca40: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
ca50: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
ca60: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ca70: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ca80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ca90: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
caa0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
cab0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
cac0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
cad0: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
cae0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
caf0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
cb00: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
cb10: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
cb20: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
cb30: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
cb40: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
cb50: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
cb60: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
cb70: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
cb80: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
cb90: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
cba0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
cbb0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
cbc0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
cbd0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
cbe0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
cbf0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
cc00: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
cc10: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
cc20: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
cc30: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
cc40: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
cc50: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
cc60: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
cc70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
cc80: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
cc90: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
cca0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ccb0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ccc0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ccd0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
cce0: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
ccf0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
cd00: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
cd10: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
cd20: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
cd30: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
cd40: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
cd50: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
cd60: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
cd70: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
cd80: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
cd90: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
cda0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
cdb0: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
cdc0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
cdd0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
cde0: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
cdf0: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
ce00: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ce10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ce20: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ce30: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ce40: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ce50: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ce60: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
ce70: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
ce80: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
ce90: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
cea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
ceb0: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
cec0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
ced0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
cee0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
cef0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
cf00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
cf10: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
cf20: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cf30: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
cf40: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
cf50: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
cf60: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
cf70: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
cf80: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
cf90: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
cfa0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
cfb0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
cfc0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
cfd0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
cfe0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
cff0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d000: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
d010: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
d020: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
d030: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
d040: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
d050: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
d060: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
d070: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
d080: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
d090: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d0a0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d0b0: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
d0c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d0d0: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
d0e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d100: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
d110: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
d120: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
d130: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
d140: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
d150: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
d160: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
d170: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
d180: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
d190: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d1a0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
d1b0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
d1c0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
d1d0: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
d1e0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
d1f0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
d200: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
d210: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
d220: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d230: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
d240: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
d250: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
d260: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
d270: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
d280: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
d290: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
d2a0: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
d2b0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d2c0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
d2d0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
d2e0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
d2f0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
d300: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
d310: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
d320: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
d330: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
d340: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
d350: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
d360: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
d370: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
d380: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
d390: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d3a0: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
d3b0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
d3c0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
d3d0: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
d3e0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
d3f0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
d400: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
d410: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
d420: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
d430: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
d440: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
d450: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
d460: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
d470: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
d480: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
d490: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
d4a0: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
d4b0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
d4c0: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
d4d0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
d4e0: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
d4f0: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
d500: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
d510: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
d520: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
d530: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
d540: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
d550: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d560: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
d570: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
d580: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
d590: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
d5a0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
d5b0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
d5c0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
d5d0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
d5e0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
d5f0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
d600: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
d610: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
d620: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
d630: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
d640: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
d650: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
d660: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
d670: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
d680: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
d690: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
d6a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
d6b0: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
d6c0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d6d0: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
d6e0: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
d6f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
d700: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
d710: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
d720: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
d730: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69  equired due to i
d740: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64  nternal overhead
d750: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
d760: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
d770: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
d780: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
d790: 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
d7a0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
d7b0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
d7c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
d7d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
d7e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 70  scratch buffer p
d7f0: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
d800: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
d810: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65  t to the expecte
d820: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
d830: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53   of threads.  ^S
d840: 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
d850: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
d860: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
d870: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
d880: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
d890: 61 73 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65  ase.** page size
d8a0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
d8b0: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
d8c0: 6e 61 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  nal scratch memo
d8d0: 72 79 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68  ry beyond .** wh
d8e0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
d8f0: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
d900: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
d910: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
d920: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
d930: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
d940: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
d950: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
d960: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d970: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
d980: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
d990: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
d9a0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
d9b0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
d9c0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
d9d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
d9e0: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
d9f0: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
da00: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
da10: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
da20: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
da30: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
da40: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
da50: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
da60: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
da70: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
da80: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
da90: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
daa0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
dab0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
dac0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
dad0: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
dae0: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
daf0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
db00: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
db10: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
db20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
db30: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
db40: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
db50: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
db60: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
db70: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
db80: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
db90: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
dba0: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
dbb0: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
dbc0: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
dbd0: 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
dbe0: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
dbf0: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
dc00: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
dc10: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
dc20: 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
dc30: 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
dc40: 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
dc50: 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
dc60: 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
dc70: 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
dc80: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
dc90: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
dca0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
dcb0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
dcc0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
dcd0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
dce0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
dcf0: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
dd00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
dd10: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
dd20: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
dd30: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
dd40: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
dd50: 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
dd60: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
dd70: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
dd80: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
dd90: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
dda0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
ddb0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
ddc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
ddd0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
dde0: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
ddf0: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65  e space..** ^The
de00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
de10: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72  might use one or
de20: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62   more of the N b
de30: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a  uffers to hold .
de40: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  ** memory accoun
de50: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ting information
de60: 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  . The pointer in
de70: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
de80: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
de90: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
dea0: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
deb0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
dec0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
ded0: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
dee0: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
def0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
df00: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
df10: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
df20: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
df30: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
df40: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
df50: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
df60: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
df70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
df80: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
df90: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
dfa0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
dfb0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
dfc0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
dfd0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
dfe0: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
dff0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
e000: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
e010: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
e020: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
e030: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
e040: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
e050: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
e060: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
e070: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
e080: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
e090: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
e0a0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
e0b0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
e0c0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
e0d0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
e0e0: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
e0f0: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
e100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
e110: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
e120: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
e130: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e140: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
e150: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
e160: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
e170: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
e180: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
e190: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
e1a0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
e1b0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
e1c0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
e1d0: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
e1e0: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
e1f0: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
e200: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
e210: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
e220: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
e230: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
e240: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
e250: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
e260: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
e270: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
e280: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
e290: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
e2a0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
e2b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e2c0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
e2d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
e2e0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
e2f0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
e300: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
e310: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
e320: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
e330: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e340: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
e350: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
e360: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
e370: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
e380: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
e390: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
e3a0: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
e3b0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e3c0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
e3d0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
e3e0: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
e3f0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
e400: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
e410: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
e420: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
e430: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
e440: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
e450: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
e460: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
e470: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
e480: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
e490: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
e4a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e4b0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
e4c0: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
e4d0: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
e4e0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
e4f0: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
e500: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
e510: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
e520: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e530: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
e540: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
e550: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
e560: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
e570: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e580: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
e590: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
e5a0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
e5b0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
e5c0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
e5d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
e5e0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
e5f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
e600: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e610: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
e620: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e630: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
e640: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
e650: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
e660: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
e670: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
e680: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
e690: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
e6a0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
e6b0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
e6c0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
e6d0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
e6e0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
e6f0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
e700: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
e710: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
e720: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
e730: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e740: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e750: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
e760: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
e770: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
e780: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
e790: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
e7a0: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
e7b0: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
e7c0: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
e7d0: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
e7e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e7f0: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
e800: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
e810: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
e820: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
e830: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
e840: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
e850: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e860: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
e870: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
e880: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
e890: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
e8a0: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
e8b0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
e8c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
e8d0: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
e8e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e8f0: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
e900: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e910: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
e920: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
e930: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
e940: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
e950: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
e960: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
e970: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
e980: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
e990: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e9a0: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
e9b0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
e9c0: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
e9d0: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
e9e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
e9f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
ea00: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
ea10: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
ea20: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
ea30: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
ea40: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
ea50: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
ea60: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
ea70: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
ea80: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ea90: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
eaa0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
eab0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
eac0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ead0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
eae0: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
eaf0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
eb00: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
eb10: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
eb20: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
eb30: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
eb40: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
eb50: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
eb60: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
eb70: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
eb80: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
eb90: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
eba0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
ebb0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
ebc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
ebd0: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
ebe0: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ebf0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ec00: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ec10: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ec20: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
ec30: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
ec40: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
ec50: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
ec60: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
ec70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ec80: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
ec90: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
eca0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ecb0: 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
ecc0: 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
ecd0: 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
ece0: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
ecf0: 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
ed00: 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
ed10: 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
ed20: 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
ed30: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
ed40: 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
ed50: 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
ed60: 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
ed70: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
ed80: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
ed90: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
eda0: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
edb0: 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
edc0: 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
edd0: 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
ede0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
edf0: 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
ee00: 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
ee10: 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
ee20: 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
ee30: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
ee40: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ee50: 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
ee60: 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
ee70: 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
ee80: 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
ee90: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
eea0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
eeb0: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
eec0: 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
eed0: 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
eee0: 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
eef0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
ef00: 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
ef10: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
ef20: 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
ef30: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
ef40: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
ef50: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
ef60: 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
ef70: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
ef80: 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
ef90: 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
efa0: 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
efb0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
efc0: 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
efd0: 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
efe0: 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
eff0: 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
f000: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
f010: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
f020: 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
f030: 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
f040: 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
f050: 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
f060: 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
f070: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
f080: 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
f090: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
f0a0: 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
f0b0: 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
f0c0: 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
f0d0: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
f0e0: 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
f0f0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
f100: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
f110: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
f120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
f130: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
f140: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
f150: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
f160: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
f170: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
f180: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f190: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
f1a0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
f1b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f1c0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
f1d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
f1e0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
f1f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f200: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
f210: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
f220: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
f230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f240: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
f250: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
f260: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
f270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f280: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
f290: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
f2a0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
f2b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f2c0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
f2d0: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
f2e0: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
f2f0: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
f300: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f310: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
f320: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
f330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f340: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
f350: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
f360: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
f370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f380: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
f390: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
f3a0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f3b0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
f3c0: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
f3d0: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
f3e0: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
f3f0: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
f400: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f410: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
f420: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
f430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f440: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
f450: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
f460: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
f470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f480: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
f490: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
f4a0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f4b0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f4c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f4d0: 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
f4e0: 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
f4f0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
f500: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
f510: 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
f520: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
f530: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
f540: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
f550: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
f560: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f570: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
f580: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
f590: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f5a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
f5b0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
f5c0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
f5d0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
f5e0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
f5f0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
f600: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
f610: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
f620: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f630: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
f640: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
f650: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
f660: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
f670: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
f680: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f690: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
f6a0: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
f6b0: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
f6c0: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
f6d0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
f6e0: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
f6f0: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
f700: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
f710: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
f720: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
f730: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
f740: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
f750: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
f760: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
f770: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
f780: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
f790: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
f7a0: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
f7b0: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
f7c0: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
f7d0: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
f7e0: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
f7f0: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
f800: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f810: 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
f820: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
f830: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
f840: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
f850: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
f860: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
f870: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
f880: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
f890: 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
f8a0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f8b0: 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
f8c0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f8d0: 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
f8e0: 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
f8f0: 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
f900: 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
f910: 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
f920: 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
f930: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
f940: 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
f950: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
f960: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
f970: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
f980: 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
f990: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
f9a0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
f9b0: 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
f9c0: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
f9d0: 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
f9e0: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
f9f0: 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
fa00: 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
fa10: 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
fa20: 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
fa30: 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
fa40: 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
fa50: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
fa60: 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
fa70: 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
fa80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
fa90: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
faa0: 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
fab0: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
fac0: 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
fad0: 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
fae0: 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
faf0: 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70  maller.** multip
fb00: 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 61 6c  le of 8.  See al
fb10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  so: [SQLITE_CONF
fb20: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64  IG_LOOKASIDE]</d
fb30: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
fb40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fb50: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
fb60: 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20  IDE    1001  /* 
fb70: 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
fb80: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
fb90: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
fba0: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
fbb0: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
fbc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
fbd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
fbe0: 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
fbf0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
fc00: 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
fc10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
fc20: 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
fc30: 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
fc40: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
fc50: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
fc60: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
fc70: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
fc80: 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
fc90: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
fca0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
fcb0: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
fcc0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
fcd0: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
fce0: 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
fcf0: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
fd00: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
fd10: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
fd20: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
fd30: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
fd40: 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
fd50: 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
fd60: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
fd70: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
fd80: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
fd90: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
fda0: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
fdb0: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
fdc0: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
fdd0: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
fde0: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
fdf0: 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
fe00: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
fe10: 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
fe20: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
fe30: 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
fe40: 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
fe50: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
fe60: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
fe70: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
fe80: 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
fe90: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
fea0: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
feb0: 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
fec0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
fed0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
fee0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
fef0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ff00: 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  t.  ^If no succe
ff10: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
ff20: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
ff30: 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
ff40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ff50: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
ff60: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
ff70: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
ff80: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
ff90: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72  ger, then the [r
ffa0: 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
ffb0: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20  erted.** row is 
ffc0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
ffd0: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67   routine as long
ffe0: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
fff0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
10000 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
10010 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
10020 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
10030 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10040 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f  ne.** reverts to
10050 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
10060 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
10070 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
10080 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  d.)^.**.** ^An [
10090 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
100a0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
100b0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
100c0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
100d0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
100e0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
100f0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
10100 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
10110 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
10120 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
10130 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
10140 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
10150 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
10160 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
10170 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
10180 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
10190 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
101a0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
101b0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
101c0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
101d0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
101e0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
101f0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
10200 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
10210 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
10220 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
10230 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
10240 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
10250 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
10260 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
10270 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
10280 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
10290 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
102a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
102b0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
102c0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
102d0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
102e0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
102f0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
10300 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
10310 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
10320 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
10330 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
10340 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
10350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
10360 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
10370 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
10380 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
10390 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
103a0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
103b0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
103c0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
103d0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
103e0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
103f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
10400 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
10410 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
10420 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
10430 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
10440 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
10450 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
10460 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
10470 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
10480 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
10490 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
104a0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
104b0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
104c0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
104d0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
104e0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
104f0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
10500 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
10510 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10520 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
10530 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
10540 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
10550 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
10560 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
10570 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
10580 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
10590 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
105a0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
105b0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
105c0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
105d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
105e0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
105f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
10600 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10610 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
10620 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
10630 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
10640 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
10650 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
10660 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
10670 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
10680 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
10690 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
106a0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
106b0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
106c0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
106d0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
106e0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
106f0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
10700 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
10710 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10720 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
10730 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
10740 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
10750 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
10760 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
10770 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
10780 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
10790 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
107a0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
107b0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
107c0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
107d0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
107e0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
107f0 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
10800 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
10810 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
10820 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
10830 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
10840 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
10850 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
10860 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
10870 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
10880 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
10890 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
108a0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
108b0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
108c0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
108d0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
108e0 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
108f0 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
10900 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
10910 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
10920 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
10930 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
10940 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
10950 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
10960 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
10970 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
10980 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
10990 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
109a0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
109b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
109c0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
109d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
109e0 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
109f0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
10a00 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
10a10 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
10a20 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
10a30 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
10a40 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
10a50 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
10a60 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
10a70 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
10a80 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
10a90 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
10aa0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
10ab0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
10ac0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
10ad0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
10ae0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
10af0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
10b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10b10 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
10b20 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
10b30 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
10b40 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
10b50 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
10b60 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
10b70 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
10b80 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
10b90 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
10ba0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
10bb0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
10bc0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
10bd0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
10be0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
10bf0 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
10c00 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
10c10 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
10c20 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
10c30 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
10c40 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
10c50 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
10c60 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
10c70 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
10c80 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
10c90 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
10ca0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
10cb0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
10cc0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
10cd0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
10ce0 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
10cf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10d00 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
10d10 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
10d20 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
10d30 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
10d40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
10d50 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
10d60 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
10d70 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
10d80 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
10d90 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
10da0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
10db0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
10dc0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
10dd0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
10de0 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
10df0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
10e00 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
10e10 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
10e20 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
10e30 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
10e40 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
10e50 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
10e60 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
10e70 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
10e80 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
10e90 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
10ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
10eb0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
10ec0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
10ed0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
10ee0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
10ef0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
10f00 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
10f10 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
10f20 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
10f30 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
10f40 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
10f50 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
10f60 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
10f70 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
10f80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
10f90 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
10fa0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
10fb0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
10fc0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
10fd0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
10fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10ff0 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
11000 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
11010 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
11020 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11030 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
11040 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
11050 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
11060 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
11070 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
11080 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
11090 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
110a0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
110b0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
110c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
110d0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
110e0 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
110f0 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
11100 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
11110 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
11120 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
11130 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
11140 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
11150 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
11160 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
11170 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
11180 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
11190 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
111a0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
111b0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
111c0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
111d0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
111e0 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
111f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
11200 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
11210 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
11220 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
11230 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
11240 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
11250 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
11260 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
11270 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
11280 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
11290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
112a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
112b0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
112c0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
112d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
112e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
112f0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
11300 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
11310 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
11320 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
11330 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
11340 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
11350 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
11360 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
11370 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
11380 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
11390 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
113a0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
113b0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
113c0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
113d0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
113e0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
113f0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
11400 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
11410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11420 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
11430 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
11440 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
11450 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
11460 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
11470 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
11480 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
11490 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
114a0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
114b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
114c0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
114d0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
114e0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
114f0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
11500 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
11510 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
11520 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
11530 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
11540 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
11550 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
11560 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
11570 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
11580 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
11590 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
115a0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
115b0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
115c0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
115d0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
115e0 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
115f0 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
11600 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
11610 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
11620 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
11630 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
11640 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
11650 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11660 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
11670 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
11680 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
11690 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
116a0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
116b0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
116c0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
116d0 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
116e0 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
116f0 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
11700 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
11710 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
11720 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
11730 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
11740 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
11750 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
11760 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11770 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
11780 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
11790 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
117a0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
117b0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
117c0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
117d0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
117e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
117f0 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
11800 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
11810 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
11820 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
11830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11840 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
11850 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
11860 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
11870 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
11880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
11890 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
118a0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
118b0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
118c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
118d0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
118e0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
118f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11900 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
11910 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
11920 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
11930 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
11940 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
11950 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
11960 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
11970 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11980 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
11990 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
119a0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
119b0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
119c0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
119d0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
119e0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
119f0 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
11a00 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11a10 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
11a20 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
11a30 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
11a40 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
11a50 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
11a60 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
11a70 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
11a80 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
11a90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
11aa0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
11ab0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
11ac0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11ad0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
11ae0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
11af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11b00 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
11b10 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11b20 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
11b30 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
11b40 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
11b50 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
11b60 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11b70 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11b80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
11b90 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
11ba0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
11bb0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
11bc0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
11bd0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
11be0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
11bf0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
11c00 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
11c10 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
11c20 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
11c30 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
11c40 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
11c50 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
11c60 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
11c70 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
11c80 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
11c90 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
11ca0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
11cb0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
11cc0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
11cd0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
11ce0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
11cf0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
11d00 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
11d10 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
11d20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
11d30 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
11d40 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
11d50 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
11d60 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
11d70 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
11d80 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
11d90 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
11da0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
11db0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
11dc0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
11dd0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
11de0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
11df0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
11e00 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
11e10 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
11e20 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
11e30 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
11e40 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
11e50 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
11e60 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
11e70 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
11e80 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
11e90 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
11ea0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
11eb0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
11ec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
11ed0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
11ee0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
11ef0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
11f00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11f10 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
11f20 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
11f30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
11f40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
11f50 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
11f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
11f70 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
11f80 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
11f90 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
11fa0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
11fb0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
11fc0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
11fd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
11fe0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
11ff0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
12000 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
12010 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
12020 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12030 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
12040 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
12050 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12060 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
12070 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
12080 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
12090 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
120a0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
120b0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
120c0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
120d0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
120e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
120f0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
12100 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
12110 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
12120 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
12130 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
12140 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
12150 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
12160 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
12170 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12180 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12190 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
121a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
121b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
121c0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
121d0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
121e0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
121f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12200 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
12210 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
12220 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
12230 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
12240 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
12250 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
12260 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
12270 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
12280 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
12290 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
122a0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
122b0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
122c0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
122d0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
122e0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
122f0 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
12300 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
12310 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
12320 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
12330 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
12340 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12350 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
12360 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
12370 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
12380 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
12390 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
123a0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
123b0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
123c0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
123d0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
123e0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
123f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12400 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
12410 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
12420 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
12430 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
12440 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
12450 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
12460 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
12470 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
12480 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
12490 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
124a0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
124b0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
124c0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
124d0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
124e0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
124f0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
12500 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
12510 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12520 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
12530 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
12540 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
12550 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
12560 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
12570 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12580 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12590 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
125a0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
125b0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
125c0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
125d0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
125e0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
125f0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
12600 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
12610 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
12620 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
12630 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
12640 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
12650 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
12660 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
12670 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
12680 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
12690 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
126a0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
126b0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
126c0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
126d0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
126e0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
126f0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
12700 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
12710 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12720 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
12730 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
12740 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
12750 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
12760 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
12770 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
12780 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
12790 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
127a0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
127b0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
127c0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
127d0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
127e0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
127f0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
12800 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
12810 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
12820 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
12830 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
12840 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
12850 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
12860 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
12870 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
12880 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
12890 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
128a0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
128b0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
128c0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
128d0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
128e0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
128f0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
12900 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
12910 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
12920 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
12930 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
12940 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
12950 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
12960 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
12970 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
12980 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
12990 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
129a0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
129b0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
129c0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
129d0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
129e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
129f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
12a00 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
12a10 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
12a20 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
12a30 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
12a40 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
12a50 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
12a60 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
12a70 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
12a80 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
12a90 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
12aa0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
12ab0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
12ac0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
12ad0 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
12ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
12af0 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
12b00 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
12b10 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
12b20 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
12b30 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
12b40 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
12b50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
12b60 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
12b70 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
12b80 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
12b90 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
12ba0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
12bb0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
12bc0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
12bd0 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
12be0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
12bf0 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
12c00 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
12c10 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
12c20 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
12c30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
12c40 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
12c50 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
12c60 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
12c70 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
12c80 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
12c90 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
12ca0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
12cb0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
12cc0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
12cd0 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
12ce0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
12cf0 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
12d00 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
12d10 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
12d20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
12d30 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
12d40 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
12d50 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
12d60 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
12d70 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
12d80 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
12d90 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
12da0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12db0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
12dc0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
12dd0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
12de0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
12df0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
12e00 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
12e10 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
12e20 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
12e30 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
12e40 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
12e50 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
12e60 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
12e70 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
12e80 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
12e90 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
12ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
12eb0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
12ec0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
12ed0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
12ee0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
12ef0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
12f00 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
12f10 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
12f20 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
12f30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
12f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12f50 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
12f60 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
12f70 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
12f80 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
12f90 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
12fa0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
12fb0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
12fc0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
12fd0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
12fe0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
12ff0 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
13000 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
13010 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
13020 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
13030 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
13040 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
13050 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
13060 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
13070 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
13080 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
13090 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
130a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
130b0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
130c0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
130d0 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
130e0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
130f0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
13100 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
13110 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
13120 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
13130 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
13140 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
13150 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
13160 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
13170 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
13180 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
13190 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
131a0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
131b0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
131c0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
131d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
131e0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
131f0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
13200 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
13210 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
13220 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
13230 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
13240 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
13250 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
13260 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
13270 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
13280 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
13290 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
132a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
132b0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
132c0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
132d0 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
132e0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
132f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
13300 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
13310 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
13320 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
13330 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
13340 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
13350 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
13360 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
13370 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
13380 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
13390 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
133a0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
133b0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
133c0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
133d0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
133e0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
133f0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
13400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
13410 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
13420 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
13430 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
13440 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
13450 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
13460 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
13470 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
13480 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
13490 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
134a0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
134b0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
134c0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
134d0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
134e0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
134f0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
13500 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
13510 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
13520 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
13530 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
13540 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
13550 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
13560 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
13570 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
13580 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
13590 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
135a0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
135b0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
135c0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
135d0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
135e0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
135f0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
13600 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
13610 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
13620 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
13630 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
13640 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
13650 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
13660 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
13670 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
13680 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
13690 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
136a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
136b0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
136c0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
136d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
136e0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
136f0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
13700 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
13710 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
13720 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
13730 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
13740 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
13750 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
13760 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
13770 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70  *.** As an examp
13780 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
13790 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
137a0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
137b0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
137c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
137d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
137e0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
137f0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
13800 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
13810 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
13820 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
13830 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
13840 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
13850 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
13860 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
13870 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
13880 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
13890 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
138a0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
138b0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
138c0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
138d0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
138e0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
138f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13900 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
13910 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
13920 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
13930 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
13940 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
13950 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13960 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
13970 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
13980 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
13990 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
139a0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
139b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
139c0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
139d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
139e0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
139f0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
13a00 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
13a10 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
13a20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
13a30 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
13a40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13a50 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
13a60 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13a70 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
13a80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13a90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68  quote>.**.** ^Th
13aa0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
13ab0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
13ac0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
13ad0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
13ae0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
13af0 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
13b00 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
13b10 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
13b20 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
13b30 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
13b40 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
13b50 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
13b60 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
13b70 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
13b80 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
13b90 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
13ba0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
13bb0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
13bc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13bd0 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20  ),.** it should 
13be0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
13bf0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
13c00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
13c10 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
13c20 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
13c30 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
13c40 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
13c50 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
13c60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13c70 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
13c80 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
13c90 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
13ca0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
13cb0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
13cc0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
13cd0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
13ce0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
13cf0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
13d00 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
13d10 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
13d20 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
13d30 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  safely..**.** ^(
13d40 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
13d50 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
13d60 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
13d70 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
13d80 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
13d90 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
13da0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
13db0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
13dc0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
13dd0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
13de0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
13df0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
13e00 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
13e10 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
13e20 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
13e30 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
13e40 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
13e50 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
13e60 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
13e70 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
13e80 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
13e90 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
13ea0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
13eb0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
13ec0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
13ed0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
13ee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
13ef0 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20  sg()].)^.*/.int 
13f00 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13f10 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
13f20 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
13f30 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
13f40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
13f50 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
13f60 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
13f70 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
13f80 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
13f90 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
13fa0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
13fb0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
13fc0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
13fd0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
13fe0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
13ff0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
14000 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
14010 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
14020 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
14030 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
14040 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
14050 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
14060 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
14070 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
14080 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
14090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
140a0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
140b0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
140c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
140d0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
140e0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
140f0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
14100 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
14110 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
14120 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
14130 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
14140 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
14150 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
14160 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
14170 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
14180 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
14190 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
141a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
141b0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
141c0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
141d0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
141e0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
141f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
14200 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
14210 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
14220 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
14230 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
14240 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
14250 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
14260 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
14270 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
14280 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
14290 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e   ^(In sqlite3_sn
142a0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
142b0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
142c0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
142d0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
142e0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
142f0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
14300 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
14310 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
14320 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
14330 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
14340 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
14350 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14360 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
14370 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
14380 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
14390 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
143a0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
143b0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
143c0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
143d0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
143e0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
143f0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
14400 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
14410 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
14420 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
14430 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14440 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
14450 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
14460 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
14470 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14480 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
14490 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
144a0 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
144b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
144c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
144d0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
144e0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
144f0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
14500 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
14510 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
14520 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14530 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
14540 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
14550 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
14560 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
14570 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
14580 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
14590 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
145a0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
145b0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
145c0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
145d0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
145e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
145f0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
14600 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
14610 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
14620 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
14630 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
14640 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
14650 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
14660 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
14670 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
14680 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
14690 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
146a0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
146b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
146c0 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
146d0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
146e0 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
146f0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
14700 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
14710 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
14720 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
14730 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
14740 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
14750 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
14760 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
14770 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
14780 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
14790 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
147a0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
147b0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
147c0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
147d0 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
147e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
147f0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
14800 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
14810 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
14820 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
14830 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
14840 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
14850 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
14860 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
14870 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
14880 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
14890 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
148a0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
148b0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
148c0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
148d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
148e0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
148f0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
14900 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
14910 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
14920 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
14930 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14940 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
14950 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
14960 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
14970 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14980 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
14990 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
149a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
149b0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
149c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
149d0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
149e0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
149f0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
14a00 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
14a10 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
14a20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
14a30 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
14a40 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
14a50 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
14a60 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14a70 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
14a80 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
14a90 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
14aa0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
14ab0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
14ac0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
14ad0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
14ae0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
14af0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14b00 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
14b10 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
14b20 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
14b30 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
14b40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14b50 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
14b60 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
14b70 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
14b80 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
14b90 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
14ba0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
14bb0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
14bc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
14bd0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
14be0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
14bf0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
14c00 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14c10 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
14c20 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
14c30 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
14c40 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
14c50 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
14c60 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
14c70 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
14c80 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
14c90 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
14ca0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
14cb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
14cc0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
14cd0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
14ce0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
14cf0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
14d00 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
14d10 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
14d20 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
14d30 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
14d40 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
14d50 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
14d60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
14d70 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
14d80 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
14d90 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
14da0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
14db0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
14dc0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
14dd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
14de0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
14df0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
14e00 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
14e10 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
14e20 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
14e30 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
14e40 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
14e50 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
14e60 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
14e70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14e80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
14e90 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
14ea0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
14eb0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
14ec0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
14ed0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
14ee0 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
14ef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
14f00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
14f10 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
14f20 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
14f30 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
14f40 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
14f50 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
14f60 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
14f70 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
14f80 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
14f90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14fa0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
14fb0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
14fc0 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
14fd0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
14fe0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
14ff0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
15000 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
15010 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
15020 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
15030 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
15040 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
15050 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15060 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
15070 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
15080 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
15090 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
150a0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
150b0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
150c0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
150d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
150e0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
150f0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
15100 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
15110 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
15120 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
15130 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
15140 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
15150 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
15160 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
15170 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
15180 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
15190 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
151a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
151b0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
151c0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
151d0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
151e0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
151f0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
15200 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
15210 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
15220 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
15230 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
15240 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
15250 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
15260 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
15270 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
15280 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
15290 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
152a0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
152b0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
152c0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
152d0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
152e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
152f0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
15300 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
15310 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
15320 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
15330 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
15340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15350 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
15360 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
15370 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
15380 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
15390 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
153a0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
153b0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
153c0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
153d0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
153e0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
153f0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
15400 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
15410 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
15420 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
15430 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
15440 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
15450 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
15460 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
15470 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
15480 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
15490 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
154a0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
154b0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
154c0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
154d0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
154e0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
154f0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
15500 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
15510 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
15520 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
15530 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
15540 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
15550 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
15560 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
15570 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
15580 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
15590 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
155a0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
155b0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
155c0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
155d0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
155e0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
155f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
15600 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
15610 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
15620 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
15630 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
15640 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
15650 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
15660 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15670 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
15680 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
15690 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
156a0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
156b0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
156c0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
156d0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
156e0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
156f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15700 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
15710 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
15720 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15730 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
15740 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
15750 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
15760 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
15770 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
15780 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
15790 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
157a0 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
157b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
157c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
157d0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
157e0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
157f0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
15800 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
15810 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
15820 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
15830 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
15840 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
15850 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
15860 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
15870 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
15880 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
15890 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
158a0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
158b0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
158c0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
158d0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
158e0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
158f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15900 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
15910 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
15920 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
15930 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
15940 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
15950 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15960 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
15970 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
15980 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
15990 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
159a0 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
159b0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
159c0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
159d0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
159e0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a  byte boundary..*
159f0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
15a00 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
15a10 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
15a20 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
15a30 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
15a40 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
15a50 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
15a60 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
15a70 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
15a80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
15a90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
15aa0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
15ab0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
15ac0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
15ad0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
15ae0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
15af0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
15b00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
15b10 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
15b20 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
15b30 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
15b40 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
15b50 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
15b60 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
15b70 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
15b80 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
15b90 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
15ba0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
15bb0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
15bc0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
15bd0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
15be0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
15bf0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
15c00 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
15c10 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
15c20 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
15c30 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
15c40 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
15c50 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
15c60 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
15c70 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15c80 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
15c90 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
15ca0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
15cb0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
15cc0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
15cd0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
15ce0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
15cf0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
15d00 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
15d10 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
15d20 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
15d30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15d40 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
15d50 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
15d60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
15d70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15d80 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
15d90 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
15da0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
15db0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
15dc0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
15dd0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15de0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
15df0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
15e00 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
15e10 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
15e20 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
15e30 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
15e40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
15e50 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
15e60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
15e70 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
15e80 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
15e90 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
15ea0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
15eb0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
15ec0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
15ed0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
15ee0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
15ef0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
15f00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
15f10 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
15f20 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
15f30 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
15f40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
15f50 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
15f60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
15f70 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
15f80 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
15f90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
15fa0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
15fb0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
15fc0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
15fd0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
15fe0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
15ff0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
16000 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
16010 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
16020 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
16030 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16040 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
16050 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
16060 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
16070 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
16080 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
16090 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
160a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
160b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
160c0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
160d0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
160e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
160f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
16100 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
16110 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
16120 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
16130 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
16140 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
16150 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
16160 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
16170 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
16180 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
16190 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
161a0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
161b0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
161c0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
161d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
161e0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
161f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
16200 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
16210 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16220 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
16230 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16240 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
16250 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
16260 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
16270 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
16280 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
16290 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
162a0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
162b0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
162c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
162d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
162e0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
162f0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
16300 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
16310 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
16320 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
16330 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
16340 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
16350 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
16360 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
16370 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
16380 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
16390 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
163a0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
163b0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
163c0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
163d0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
163e0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
163f0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
16400 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
16410 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
16420 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
16430 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
16440 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
16450 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
16460 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
16470 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
16480 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
16490 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
164a0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
164b0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
164c0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
164d0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
164e0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
164f0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
16500 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
16510 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
16520 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
16530 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
16540 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
16550 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
16560 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
16570 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
16580 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
16590 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
165a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
165b0 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
165c0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
165d0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
165e0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
165f0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
16600 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
16610 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
16620 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
16630 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
16640 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
16650 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
16660 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
16670 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
16680 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
16690 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
166a0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
166b0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
166c0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
166d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
166e0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
166f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16700 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
16710 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
16720 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
16730 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16740 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16750 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
16760 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
16770 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
16780 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
16790 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
167a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
167b0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
167c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
167d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
167e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
167f0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
16800 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
16810 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
16820 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
16830 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
16840 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
16850 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
16860 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16870 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16880 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
16890 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
168a0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
168b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
168c0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
168d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
168e0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
168f0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
16900 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
16910 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
16920 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
16930 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
16940 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
16950 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
16960 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
16970 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
16980 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
16990 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
169a0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
169b0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
169c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
169d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
169e0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
169f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
16a00 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
16a10 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
16a20 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
16a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16a40 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
16a50 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
16a60 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
16a70 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
16a80 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
16a90 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
16aa0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
16ab0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
16ac0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
16ad0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
16ae0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
16af0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
16b00 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
16b10 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
16b20 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
16b30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16b40 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16b50 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
16b60 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
16b70 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
16b80 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
16b90 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
16ba0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
16bb0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
16bc0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
16bd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
16be0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16bf0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
16c00 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
16c10 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
16c20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16c30 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
16c40 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16c50 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
16c60 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
16c70 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
16c80 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
16c90 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
16ca0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
16cb0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
16cc0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
16cd0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
16ce0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
16cf0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
16d00 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
16d10 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
16d20 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
16d30 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
16d40 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
16d50 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
16d60 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
16d70 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
16d80 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
16d90 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
16da0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
16db0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
16dc0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
16dd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
16de0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
16df0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
16e00 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
16e10 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
16e20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
16e30 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
16e40 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
16e50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
16e60 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
16e70 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
16e80 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
16e90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
16ea0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
16eb0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
16ec0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
16ed0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
16ee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
16ef0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
16f00 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
16f10 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
16f20 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
16f30 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
16f40 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
16f50 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
16f60 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
16f70 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
16f80 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
16f90 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
16fa0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
16fb0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
16fc0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
16fd0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
16fe0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
16ff0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17000 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
17010 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
17020 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
17030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
17040 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
17050 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
17060 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
17070 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
17080 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
17090 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
170a0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
170b0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
170c0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
170d0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
170e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
170f0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
17100 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
17110 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
17120 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
17130 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
17140 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
17150 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
17160 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
17170 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
17180 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
17190 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
171a0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
171b0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
171c0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
171d0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
171e0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
171f0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
17200 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
17210 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
17220 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
17230 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
17240 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
17250 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
17260 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
17270 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
17280 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
17290 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
172a0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
172b0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
172c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
172d0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
172e0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
172f0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
17300 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
17310 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
17320 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
17330 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
17340 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
17350 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
17360 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
17370 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
17380 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
17390 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
173a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
173b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
173c0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
173d0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
173e0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
173f0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
17400 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
17410 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
17420 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
17430 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
17440 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
17450 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17460 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
17470 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
17480 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
17490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
174a0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
174b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
174c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
174d0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
174e0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
174f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
17500 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
17510 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
17520 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
17530 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
17540 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
17550 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
17560 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
17570 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
17580 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
17590 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
175a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
175b0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
175c0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
175d0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
175e0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
175f0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
17600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
17610 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
17620 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
17630 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17640 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
17650 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
17660 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17670 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
17680 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
17690 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
176a0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
176b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
176c0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
176d0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
176e0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
176f0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
17700 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
17710 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
17720 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
17730 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
17740 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
17750 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
17760 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
17770 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
17780 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
17790 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
177a0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
177b0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
177c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
177d0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
177e0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
177f0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
17800 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17810 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
17820 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17830 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
17840 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
17850 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
17860 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
17870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
17880 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17890 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
178a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
178b0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
178c0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
178d0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
178e0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
178f0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
17900 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
17910 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
17920 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
17930 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
17940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
17950 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17960 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
17970 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
17980 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
17990 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
179a0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
179b0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
179c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
179d0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
179e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
179f0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
17a00 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
17a10 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
17a20 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
17a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17a40 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
17a50 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
17a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17a70 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
17a80 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
17a90 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
17aa0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
17ab0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
17ac0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
17ad0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
17ae0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
17af0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17b00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
17b10 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
17b20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
17b30 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
17b40 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
17b50 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
17b60 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
17b70 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
17b80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17b90 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
17ba0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
17bb0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
17bc0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
17bd0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
17be0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
17bf0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
17c00 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
17c10 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
17c20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
17c30 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17c40 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
17c50 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
17c60 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
17c70 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
17c80 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
17c90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17ca0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
17cb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
17cc0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
17cd0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
17ce0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
17cf0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
17d00 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
17d10 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
17d20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
17d30 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17d40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
17d50 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
17d60 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
17d70 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
17d80 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
17d90 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
17da0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
17db0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
17dc0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
17dd0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
17de0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
17df0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
17e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17e20 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
17e30 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
17e40 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
17e50 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
17e60 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
17e70 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
17e80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17e90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ea0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
17eb0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
17ec0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17ed0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ef0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
17f00 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
17f10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
17f20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17f30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17f40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
17f50 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
17f60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
17f70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f90 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
17fa0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
17fb0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
17fc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17fe0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
17ff0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
18000 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
18010 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18030 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
18040 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
18050 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
18060 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18080 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
18090 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
180a0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
180b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
180c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
180d0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
180e0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
180f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18100 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18110 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18120 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
18130 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
18140 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
18150 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18160 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18170 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
18180 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
18190 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
181a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
181b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
181c0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
181d0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
181e0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
181f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18200 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
18210 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
18220 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18230 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18240 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18250 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
18260 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
18270 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
18280 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18290 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
182a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
182b0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
182c0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
182d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
182e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
182f0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
18300 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
18310 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18320 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18330 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18340 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
18350 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
18360 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18370 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18380 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18390 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
183a0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
183b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
183c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
183d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
183e0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
183f0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
18400 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
18410 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
18420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18430 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
18440 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
18450 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
18460 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
18470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18480 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
18490 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
184a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
184b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
184c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
184d0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
184e0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
184f0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
18500 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
18520 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
18530 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
18540 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
18550 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
18560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
18570 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
18580 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
18590 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
185a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
185b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
185c0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
185d0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
185e0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
185f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18600 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
18610 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
18620 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
18630 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
18640 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18650 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
18660 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
18670 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
18680 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18690 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
186a0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
186b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
186c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
186d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
186e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
186f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
18700 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
18710 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18720 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
18730 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18740 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
18750 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
18760 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18770 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
18780 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18790 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
187a0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
187b0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
187c0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
187d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
187e0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
187f0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
18800 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
18810 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
18820 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18830 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
18840 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
18850 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
18860 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18870 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
18880 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
18890 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
188a0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
188b0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
188c0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
188d0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
188e0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
188f0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
18900 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18910 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
18920 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18930 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
18940 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
18950 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
18960 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
18970 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
18980 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
18990 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
189a0 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
189b0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
189c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
189d0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
189e0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
189f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18a00 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
18a10 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
18a20 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
18a30 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
18a40 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
18a50 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
18a60 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
18a70 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
18a80 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
18a90 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
18aa0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
18ab0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
18ac0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
18ad0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
18ae0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
18af0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
18b00 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
18b10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
18b20 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
18b30 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
18b40 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
18b50 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
18b60 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
18b70 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
18b80 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
18b90 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
18ba0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
18bb0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
18bc0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
18bd0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
18be0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  n..*/.void *sqli
18bf0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
18c00 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
18c10 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
18c20 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
18c30 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
18c40 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
18c50 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
18c60 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
18c70 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
18c80 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
18c90 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
18ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18cb0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
18cc0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
18cd0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f  ^This routine co
18ce0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
18cf0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
18d00 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
18d10 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
18d20 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
18d30 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
18d40 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
18d50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18d60 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
18d70 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
18d80 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
18d90 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
18da0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
18db0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
18dc0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
18dd0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
18de0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
18df0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
18e00 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
18e10 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
18e20 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
18e30 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
18e40 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
18e50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
18e60 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
18e70 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
18e80 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
18e90 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
18ea0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
18eb0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f  dler must not do
18ec0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
18ed0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
18ee0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18ef0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
18f00 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
18f10 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
18f20 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
18f30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
18f40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18f50 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
18f60 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
18f70 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
18f80 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
18f90 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
18fa0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
18fb0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
18fc0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
18fd0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
18fe0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
18ff0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19000 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
19010 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
19020 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
19030 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
19040 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
19050 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
19060 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
19070 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
19080 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
19090 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
190a0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
190b0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
190c0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
190d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
190e0 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
190f0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
19100 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
19110 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
19120 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
19130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19140 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
19150 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
19160 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
19170 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
19180 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
19190 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
191a0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
191b0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
191c0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
191d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
191e0 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
191f0 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
19200 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
19210 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
19220 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
19230 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
19240 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
19250 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
19260 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
19270 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
19280 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
19290 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
192a0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
192b0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
192c0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
192d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
192e0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
192f0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
19300 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
19310 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
19320 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
19330 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
19340 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
19350 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
19360 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
19370 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
19380 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
19390 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
193a0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
193b0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
193c0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
193d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
193e0 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
193f0 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
19400 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
19410 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
19420 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
19430 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
19440 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
19450 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
19460 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
19470 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
19480 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
19490 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
194a0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
194b0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
194c0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
194d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
194e0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
194f0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
19500 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
19510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19520 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
19530 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
19540 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
19550 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
19560 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
19570 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
19580 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
19590 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
195a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
195b0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
195c0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
195d0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
195e0 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
195f0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
19600 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
19610 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
19620 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
19630 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
19640 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
19650 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
19660 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
19670 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
19680 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  * and/or [SQLITE
19690 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
196a0 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  HE] flags:)^.**.
196b0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
196c0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
196d0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
196e0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
196f0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
19700 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
19710 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
19720 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
19730 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
19740 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
19750 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
19760 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19770 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
19780 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
19790 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
197a0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
197b0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
197c0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
197d0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
197e0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
197f0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
19800 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
19810 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
19820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
19830 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
19840 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
19850 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
19860 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
19870 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
19880 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
19890 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
198a0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
198b0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
198c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
198d0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
198e0 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
198f0 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
19900 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
19910 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
19920 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
19930 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
19940 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
19950 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
19960 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
19970 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
19980 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
19990 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
199a0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
199b0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
199c0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
199d0 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
199e0 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
199f0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
19a00 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
19a10 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
19a20 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
19a30 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
19a40 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
19a50 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
19a60 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
19a70 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
19a80 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
19a90 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
19aa0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
19ab0 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
19ac0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
19ad0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
19ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19af0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
19b00 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
19b10 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
19b20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
19b30 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
19b40 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
19b50 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
19b60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
19b70 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
19b80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
19b90 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
19ba0 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
19bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19bc0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
19bd0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
19be0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
19bf0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
19c00 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
19c10 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
19c20 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
19c30 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
19c40 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
19c50 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
19c60 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
19c70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19c80 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
19c90 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
19ca0 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
19cb0 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
19cc0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
19cd0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
19ce0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
19cf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
19d00 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
19d10 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
19d20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
19d30 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
19d40 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
19d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
19d60 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
19d70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
19d80 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
19d90 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
19da0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
19db0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
19dc0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
19dd0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
19de0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
19df0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
19e00 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
19e10 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
19e20 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
19e30 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
19e40 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
19e50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
19e60 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
19e70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
19e80 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
19e90 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
19ea0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
19eb0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
19ec0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
19ed0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
19ee0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
19ef0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
19f00 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
19f10 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
19f20 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
19f30 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
19f40 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
19f50 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
19f60 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
19f70 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
19f80 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
19f90 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
19fa0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
19fb0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
19fc0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
19fd0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
19fe0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
19ff0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
1a000 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1a010 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1a020 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1a030 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1a040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a050 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1a060 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1a070 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1a080 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1a090 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1a0a0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1a0b0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1a0c0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1a0d0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1a0e0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1a0f0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1a100 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1a110 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1a120 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1a130 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1a140 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1a150 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a160 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1a170 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1a180 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1a190 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1a1a0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1a1b0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a1c0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1a1d0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a1e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1a1f0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1a200 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1a210 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1a220 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1a230 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1a240 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1a250 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1a260 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1a270 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1a280 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1a290 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1a2a0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1a2b0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
1a2c0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
1a2d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1a2e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1a2f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1a300 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1a310 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1a320 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a330 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a340 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1a350 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
1a360 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
1a370 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1a380 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
1a390 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a3a0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1a3b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a3c0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a3d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1a3e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1a3f0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1a400 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1a410 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1a420 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1a430 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a440 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a450 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1a460 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1a470 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1a480 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1a490 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1a4a0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1a4b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a4c0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1a4d0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
1a4e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a4f0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1a500 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1a510 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1a520 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1a530 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a540 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1a550 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1a560 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1a570 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1a580 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1a590 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1a5a0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1a5b0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1a5c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1a5d0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1a5e0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1a5f0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1a600 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1a610 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
1a620 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1a630 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
1a640 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
1a650 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
1a660 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
1a670 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
1a680 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a690 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
1a6a0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a6b0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
1a6c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1a6d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1a6e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1a6f0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1a700 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1a710 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1a720 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1a730 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1a740 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1a750 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
1a760 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1a770 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1a780 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1a790 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1a7a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1a7b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1a7c0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1a7d0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1a7e0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1a7f0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1a800 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1a810 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1a820 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1a830 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1a840 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1a850 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
1a860 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
1a870 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1a880 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1a890 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1a8a0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1a8b0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1a8c0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1a8d0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1a8e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1a8f0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1a900 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1a910 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1a920 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1a930 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1a940 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1a950 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1a960 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1a970 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1a980 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1a990 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1a9a0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1a9b0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1a9c0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1a9d0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1a9e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a9f0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1aa00 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1aa10 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1aa20 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1aa30 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1aa40 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1aa50 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1aa60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1aa70 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1aa80 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1aa90 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1aaa0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1aab0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1aac0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1aad0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1aae0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1aaf0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1ab00 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1ab10 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1ab20 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1ab30 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1ab40 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1ab50 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1ab60 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1ab70 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1ab80 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
1ab90 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1aba0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
1abb0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1abc0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
1abd0 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1abe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1abf0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1ac00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1ac10 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1ac20 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ac30 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1ac40 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
1ac50 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1ac60 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1ac70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ac80 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1ac90 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1aca0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1acb0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1acc0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1acd0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1ace0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1acf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ad00 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1ad10 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1ad20 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1ad30 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1ad40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1ad50 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1ad60 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1ad70 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1ad80 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1ad90 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1ada0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1adb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1adc0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1add0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1ade0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1adf0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1ae00 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1ae10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1ae20 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1ae30 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1ae40 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1ae50 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1ae60 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1ae70 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1ae80 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1ae90 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1aea0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1aeb0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1aec0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1aed0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1aee0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1aef0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1af00 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1af10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1af20 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1af30 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1af40 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1af50 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1af60 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1af70 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1af80 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1af90 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1afa0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1afb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1afc0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1afd0 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
1afe0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1aff0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1b000 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1b010 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1b020 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1b030 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1b040 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1b050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1b060 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1b070 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1b080 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1b090 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1b0a0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1b0b0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1b0c0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1b0d0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1b0e0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1b0f0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1b100 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1b110 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1b120 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1b130 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1b140 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1b150 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1b160 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1b170 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  mit.)^.**.** ^If
1b180 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1b190 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1b1a0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1b1b0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1b1c0 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  ^(For the limit 
1b1d0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1b1e0 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1b1f0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
1b200 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
1b210 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
1b220 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
1b230 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1b240 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
1b250 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1b260 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
1b270 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1b280 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1b290 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1b2a0 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1b2b0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1b2c0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1b2d0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1b2e0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1b2f0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1b300 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1b310 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
1b320 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
1b330 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
1b340 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
1b350 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
1b360 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
1b370 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
1b380 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
1b390 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
1b3a0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
1b3b0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
1b3c0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
1b3d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1b3e0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
1b3f0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
1b400 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
1b410 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
1b420 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
1b430 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
1b440 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
1b450 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
1b460 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
1b470 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
1b480 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
1b490 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
1b4a0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
1b4b0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
1b4c0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
1b4d0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
1b4e0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1b4f0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
1b500 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
1b510 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
1b520 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
1b530 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
1b540 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
1b550 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
1b560 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
1b570 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1b580 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
1b590 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
1b5a0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
1b5b0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
1b5c0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
1b5d0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
1b5e0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
1b5f0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
1b600 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
1b610 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
1b620 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
1b630 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
1b640 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
1b650 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
1b660 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1b670 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1b680 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
1b690 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
1b6a0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
1b6b0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1b6c0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
1b6d0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1b6e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1b6f0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
1b700 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1b710 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1b720 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
1b730 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
1b740 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
1b750 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
1b760 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1b770 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
1b780 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
1b790 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1b7a0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1b7b0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1b7c0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1b7d0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1b7e0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1b7f0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1b800 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1b810 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b820 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1b830 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b840 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1b850 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
1b860 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
1b870 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b880 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1b890 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1b8a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1b8b0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1b8c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1b8d0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1b8e0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b8f0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1b900 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b910 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1b920 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1b930 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1b940 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1b950 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1b960 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1b970 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1b980 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1b990 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1b9a0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1b9b0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1b9c0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1b9d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1b9e0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1b9f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1ba00 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1ba10 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1ba20 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1ba30 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1ba40 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1ba50 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1ba60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1ba70 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1ba80 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1ba90 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1baa0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1bab0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1bac0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1bad0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1bae0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1baf0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1bb00 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1bb10 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1bb20 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1bb30 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1bb40 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1bb50 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1bb60 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
1bb70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1bb80 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1bb90 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
1bba0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1bbb0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1bbc0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1bbd0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1bbe0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
1bbf0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
1bc00 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
1bc10 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  d>.**.** ^(<dt>S
1bc20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1bc30 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1bc40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1bc50 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1bc60 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1bc70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
1bc80 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
1bc90 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
1bca0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1bcb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1bcc0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1bcd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bce0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1bcf0 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1bd00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1bd10 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1bd20 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1bd30 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1bd40 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1bd50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1bd60 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1bd70 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1bd80 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1bd90 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1bda0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1bdb0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1bdc0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1bdd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1bde0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1bdf0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1be00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1be10 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1be20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1be30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1be40 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1be50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1be60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1be70 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1be80 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1be90 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1bea0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1beb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1bec0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1bed0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1bee0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1bef0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1bf00 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1bf10 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1bf20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1bf30 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1bf40 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1bf50 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1bf60 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1bf70 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1bf80 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1bf90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1bfa0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1bfb0 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1bfc0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1bfd0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1bfe0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1bff0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1c000 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1c010 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1c020 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1c030 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1c040 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1c050 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1c060 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1c070 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1c080 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1c090 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1c0a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c0b0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1c0c0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1c0d0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1c0e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1c0f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1c100 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1c110 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1c120 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1c130 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1c140 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1c150 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1c160 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c170 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1c180 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1c190 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1c1a0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1c1b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1c1c0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1c1d0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1c1e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c1f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1c200 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1c210 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1c220 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1c230 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1c240 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1c250 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1c260 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1c270 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1c280 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1c290 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1c2a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1c2b0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1c2c0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1c2d0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1c2e0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1c2f0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1c300 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1c310 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1c320 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1c330 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1c340 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1c350 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1c360 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1c370 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1c380 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1c390 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1c3a0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1c3b0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1c3c0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1c3d0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1c3e0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1c3f0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1c400 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1c410 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1c420 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1c430 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1c440 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1c450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1c460 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1c470 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1c480 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1c490 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1c4a0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1c4b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1c4c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1c4d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1c4e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1c4f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1c500 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1c510 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1c520 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1c530 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1c540 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1c550 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1c560 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1c570 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1c580 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1c590 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1c5a0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1c5b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1c5c0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1c5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c5e0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1c5f0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1c600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c610 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1c620 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1c630 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1c640 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1c650 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1c660 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1c670 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1c680 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1c690 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1c6a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1c6b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1c6c0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1c6d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1c6e0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1c6f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1c700 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1c710 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1c720 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1c730 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1c740 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1c750 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1c760 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1c770 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1c780 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1c790 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1c7a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1c7b0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1c7c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1c7d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c7e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1c7f0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1c800 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1c810 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1c820 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1c830 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1c840 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1c850 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1c860 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1c870 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1c880 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1c890 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1c8a0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1c8b0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1c8c0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1c8d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1c8e0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1c8f0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1c900 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1c910 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1c920 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1c930 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1c940 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1c950 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1c960 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1c970 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1c980 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1c990 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1c9a0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1c9b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1c9c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1c9d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1c9e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1c9f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1ca00 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1ca10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1ca20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1ca30 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1ca40 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1ca50 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1ca60 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 68 65  n.  ^If the sche
1ca70 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1ca80 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1ca90 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1caa0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1cab0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1cac0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1cad0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1cae0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1caf0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1cb00 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1cb10 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1cb20 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1cb30 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1cb40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1cb50 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1cb60 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1cb70 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1cb80 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1cb90 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1cba0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1cbb0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1cbc0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1cbd0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1cbe0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1cbf0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1cc00 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1cc10 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1cc20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cc30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1cc40 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1cc50 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1cc60 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1cc70 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1cc80 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1cc90 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1cca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ccb0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1ccc0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1ccd0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1cce0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1ccf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1cd00 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1cd10 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1cd20 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1cd30 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1cd40 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1cd50 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1cd60 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1cd70 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1cd80 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1cd90 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1cda0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1cdb0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1cdc0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1cdd0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1cde0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  i>.** ^If the va
1cdf0 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65  lue of a [parame
1ce00 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
1ce10 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45  eter] in the WHE
1ce20 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a  RE clause might.
1ce30 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71 75  ** change the qu
1ce40 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
1ce50 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74  tatement, then t
1ce60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  he statement may
1ce70 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1ce80 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20  ally recompiled 
1ce90 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64  (as if there had
1cea0 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63   been a schema c
1ceb0 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69  hange) on the fi
1cec0 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rst .** [sqlite3
1ced0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
1cee0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
1cef0 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  ge to the .** [s
1cf00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1cf10 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1cf20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  the [parameter].
1cf30 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
1cf40 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
1cf50 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1cf60 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1cf70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1cf80 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1cf90 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1cfa0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1cfb0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1cfc0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1cfd0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1cfe0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1cff0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1d000 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1d010 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1d020 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1d030 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1d040 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1d050 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1d060 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1d070 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1d080 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1d090 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d0a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d0b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1d0c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1d0d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1d0e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1d0f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1d100 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1d110 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1d120 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1d130 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1d140 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1d150 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1d160 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1d170 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1d180 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1d190 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1d1a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1d1b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1d1c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1d1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1d1e0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1d1f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1d200 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1d210 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1d220 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1d230 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1d240 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1d250 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1d260 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1d270 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1d280 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1d290 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1d2a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1d2b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1d2c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1d2d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1d2e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1d2f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1d300 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1d310 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1d320 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1d330 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d340 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1d350 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1d360 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1d370 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1d380 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1d390 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1d3a0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1d3b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1d3c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1d3d0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1d3e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1d3f0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1d400 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1d410 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1d420 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1d430 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1d440 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1d450 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1d460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d470 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1d480 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
1d490 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1d4a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1d4b0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1d4c0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1d4d0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1d4e0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1d4f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d500 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1d510 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1d520 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1d530 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1d540 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1d550 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d560 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
1d570 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d580 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1d590 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1d5a0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
1d5b0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1d5c0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
1d5d0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1d5e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1d5f0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1d600 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1d610 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1d620 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1d630 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1d640 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1d650 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1d660 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1d670 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1d680 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1d690 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1d6a0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1d6b0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
1d6c0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
1d6d0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
1d6e0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
1d6f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1d700 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1d710 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1d720 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1d730 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1d740 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1d750 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1d760 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1d770 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1d780 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1d790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1d7a0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1d7b0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1d7c0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1d7d0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1d7e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1d7f0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1d800 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1d810 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1d820 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1d830 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
1d840 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
1d850 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
1d860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1d870 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
1d880 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
1d890 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
1d8a0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
1d8b0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
1d8c0 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
1d8d0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
1d8e0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
1d8f0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d900 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
1d910 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
1d920 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
1d930 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d940 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
1d950 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1d960 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
1d970 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
1d980 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
1d990 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
1d9a0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1d9b0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1d9c0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
1d9d0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
1d9e0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
1d9f0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
1da00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
1da10 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
1da20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1da30 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
1da40 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
1da50 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1da60 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1da70 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1da80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1da90 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
1daa0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
1dab0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
1dac0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
1dad0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
1dae0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
1daf0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
1db00 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
1db10 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
1db20 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1db30 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1db40 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1db50 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1db60 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1db70 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
1db80 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
1db90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1dba0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1dbb0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1dbc0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1dbd0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1dbe0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1dbf0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1dc00 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1dc10 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
1dc20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1dc30 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1dc40 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1dc50 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1dc60 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1dc70 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1dc80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1dc90 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1dca0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1dcb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1dcc0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1dcd0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1dce0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1dcf0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1dd00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1dd10 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1dd20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1dd30 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1dd40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1dd50 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1dd60 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1dd70 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1dd80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1dd90 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1dda0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
1ddb0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1ddc0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1ddd0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1dde0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1ddf0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1de00 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1de10 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1de20 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1de30 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1de40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1de50 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1de60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1de70 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1de80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1de90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1dea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1deb0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1dec0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1ded0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1dee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1def0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1df00 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1df10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1df20 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1df30 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1df40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1df50 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1df60 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1df70 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1df80 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1df90 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1dfa0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1dfb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1dfc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1dfd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dfe0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1dff0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1e000 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
1e010 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1e020 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1e030 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1e040 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1e050 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1e060 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1e070 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1e080 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1e090 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
1e0a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1e0b0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
1e0c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e0d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1e0e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1e0f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1e100 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1e110 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1e120 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1e130 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1e140 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1e150 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1e160 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1e170 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1e180 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1e190 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1e1a0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1e1b0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1e1c0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1e1d0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1e1e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1e1f0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1e200 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  ifer.)^  ^The va
1e210 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
1e220 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1e230 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1e240 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
1e250 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1e260 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1e270 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1e280 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1e290 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1e2a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
1e2b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1e2c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
1e2d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1e2e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
1e2f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1e300 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1e310 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
1e320 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
1e330 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1e340 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
1e350 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
1e360 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
1e370 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
1e380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
1e390 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
1e3a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1e3b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1e3c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
1e3d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1e3e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1e3f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1e400 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1e410 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1e420 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1e430 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1e440 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1e450 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
1e460 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
1e470 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
1e480 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
1e490 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
1e4a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e4b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
1e4c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
1e4d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1e4e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1e4f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1e500 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
1e510 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
1e520 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
1e530 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1e540 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
1e550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1e560 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
1e570 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1e580 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
1e590 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1e5a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1e5b0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1e5c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
1e5d0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
1e5e0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1e5f0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1e600 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1e610 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1e620 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1e630 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1e640 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1e650 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
1e660 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
1e670 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1e680 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1e690 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
1e6a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1e6b0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1e6c0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1e6d0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1e6e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1e6f0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1e700 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1e710 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
1e720 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1e730 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
1e740 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
1e750 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
1e760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
1e770 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
1e780 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
1e790 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
1e7a0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
1e7b0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
1e7c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1e7d0 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69  h it. ^If the fi
1e7e0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1e7f0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1e800 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1e810 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1e820 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1e830 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1e840 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1e850 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1e860 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1e870 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1e880 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
1e890 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1e8a0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1e8b0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1e8c0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1e8d0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1e8e0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1e8f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1e900 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1e910 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e920 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1e930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e940 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
1e950 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
1e960 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
1e970 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
1e980 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
1e990 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
1e9a0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
1e9b0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
1e9c0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
1e9d0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
1e9e0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1e9f0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1ea00 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1ea10 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1ea20 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1ea30 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1ea40 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1ea50 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1ea60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1ea70 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
1ea80 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1ea90 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
1eaa0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1eab0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1eac0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1ead0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1eae0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
1eaf0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
1eb00 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1eb10 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
1eb20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1eb30 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
1eb40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1eb50 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
1eb60 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
1eb70 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
1eb80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
1eb90 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
1eba0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
1ebb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
1ebc0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
1ebd0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1ebe0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
1ebf0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
1ec00 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
1ec10 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
1ec20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ec30 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
1ec40 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
1ec50 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
1ec60 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
1ec70 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1ec80 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
1ec90 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
1eca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
1ecb0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
1ecc0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
1ecd0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1ece0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1ecf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ed00 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
1ed10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ed20 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1ed30 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
1ed40 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
1ed50 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
1ed60 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
1ed70 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
1ed80 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1ed90 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
1eda0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
1edb0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
1edc0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
1edd0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
1ede0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1edf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1ee00 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1ee10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ee20 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1ee30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ee40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1ee50 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1ee60 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
1ee70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1ee80 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1ee90 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1eea0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1eeb0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
1eec0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1eed0 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
1eee0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
1eef0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ef00 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
1ef10 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
1ef20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1ef30 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
1ef40 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
1ef50 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
1ef60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
1ef70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ef80 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
1ef90 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
1efa0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
1efb0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1efc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1efd0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
1efe0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1eff0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1f000 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1f010 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
1f020 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
1f030 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
1f040 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1f050 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f060 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1f070 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1f080 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1f090 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1f0a0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
1f0b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1f0c0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1f0d0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1f0e0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
1f0f0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
1f100 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f110 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
1f120 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1f130 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1f140 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1f150 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1f160 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1f170 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1f180 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1f190 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1f1a0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1f1b0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1f1c0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1f1d0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
1f1e0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
1f1f0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1f200 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1f210 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
1f220 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
1f230 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
1f240 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
1f250 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
1f260 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
1f270 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
1f280 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
1f290 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
1f2a0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
1f2b0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
1f2c0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1f2d0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
1f2e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1f2f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1f300 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1f310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f320 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1f330 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1f340 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1f350 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1f360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f370 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1f380 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1f390 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1f3a0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1f3b0 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
1f3c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1f3d0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
1f3e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1f3f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
1f400 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
1f410 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1f420 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1f430 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
1f440 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1f450 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1f460 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1f470 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1f480 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1f490 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1f4a0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1f4b0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1f4c0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1f4d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1f4e0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1f4f0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1f500 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1f510 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1f520 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1f530 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
1f540 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1f550 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1f560 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1f570 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
1f580 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
1f590 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
1f5a0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
1f5b0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1f5c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1f5d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1f5e0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1f5f0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
1f600 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
1f610 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1f620 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
1f630 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1f640 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1f650 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1f660 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
1f670 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
1f680 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
1f690 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1f6a0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1f6b0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1f6c0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1f6d0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1f6e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1f6f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1f700 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1f710 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f720 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f730 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1f740 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f750 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1f760 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1f770 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f780 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1f790 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f7a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f7b0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1f7c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1f7d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f7e0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1f7f0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1f800 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
1f810 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1f820 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1f830 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1f840 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
1f850 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1f860 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1f870 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1f880 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1f890 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1f8a0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1f8b0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
1f8c0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1f8d0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1f8e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1f8f0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
1f900 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1f910 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1f920 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1f930 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f940 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1f950 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1f960 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1f970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f980 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1f990 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1f9a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1f9b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1f9c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f9d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1f9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f9f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1fa00 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1fa10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1fa20 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1fa30 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1fa40 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1fa50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1fa60 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1fa70 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1fa80 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
1fa90 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
1faa0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
1fab0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
1fac0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
1fad0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
1fae0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1faf0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
1fb00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fb10 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
1fb20 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
1fb30 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1fb40 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1fb50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1fb60 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
1fb70 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1fb80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1fb90 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
1fba0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
1fbb0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
1fbc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1fbd0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1fbe0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1fbf0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
1fc00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
1fc10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1fc20 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
1fc30 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
1fc40 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1fc50 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1fc60 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
1fc70 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69   [UPDATE])..*/.i
1fc80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1fc90 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1fca0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1fcb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1fcc0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1fcd0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
1fce0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1fcf0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
1fd00 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
1fd10 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
1fd20 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
1fd30 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1fd40 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1fd50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1fd60 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
1fd70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1fd80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1fd90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1fda0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1fdb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1fdc0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
1fdd0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1fde0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1fdf0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1fe00 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
1fe10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fe20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1fe30 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1fe40 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1fe50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1fe60 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1fe70 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1fe80 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
1fe90 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
1fea0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
1feb0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
1fec0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1fed0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1fee0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1fef0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ff00 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
1ff10 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1ff20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1ff30 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1ff40 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
1ff50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1ff60 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1ff70 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
1ff80 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1ff90 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
1ffa0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1ffb0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1ffc0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1ffd0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1ffe0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1fff0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
20000 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
20010 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
20020 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
20030 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
20040 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
20050 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
20060 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
20070 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
20080 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
20090 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
200a0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
200b0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
200c0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
200d0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
200e0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
200f0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
20100 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
20110 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
20120 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
20130 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
20140 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
20150 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
20160 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
20170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20180 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
20190 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
201a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
201b0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
201c0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
201d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
201e0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
201f0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
20200 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
20210 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
20220 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
20230 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
20240 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
20250 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
20260 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
20270 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
20280 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
20290 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
202a0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
202b0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
202c0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
202d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
202e0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
202f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
20300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
20310 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
20320 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20330 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
20340 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
20350 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
20360 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
20370 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
20380 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
20390 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
203a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
203b0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
203c0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
203d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
203e0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
203f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
20400 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
20410 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
20420 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
20430 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
20440 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
20450 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
20460 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
20470 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
20480 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
20490 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
204a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
204b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
204c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
204d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
204e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
204f0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
20500 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
20510 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
20520 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
20530 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
20540 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
20550 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
20560 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
20570 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
20580 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
20590 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
205a0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
205b0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
205c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
205d0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
205e0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
205f0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
20600 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
20610 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
20620 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
20630 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
20640 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
20650 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
20660 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20670 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
20680 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
20690 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
206a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
206b0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
206c0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
206d0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
206e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
206f0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
20700 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
20710 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
20720 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
20730 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
20740 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
20750 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
20760 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
20770 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
20780 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
20790 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
207a0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
207b0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
207c0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
207d0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
207e0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
207f0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
20800 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
20810 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
20820 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
20830 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
20840 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20850 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
20860 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
20870 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
20880 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
20890 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
208a0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
208b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
208c0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
208d0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
208e0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
208f0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
20900 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
20910 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
20920 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
20930 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
20940 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
20950 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
20960 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
20970 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
20980 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20990 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
209a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
209b0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
209c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
209d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
209e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
209f0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
20a00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20a10 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20a20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
20a30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20a40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
20a50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20a60 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
20a70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20a80 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20a90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20aa0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
20ab0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20ac0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
20ae0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
20af0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20b00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
20b10 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
20b20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
20b30 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
20b40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
20b50 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20b60 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
20b70 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
20b80 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
20b90 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
20ba0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
20bb0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
20bc0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
20bd0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
20be0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
20bf0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
20c00 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
20c10 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
20c20 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
20c30 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
20c40 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
20c50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
20c60 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20c70 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
20c80 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
20c90 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
20ca0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
20cb0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
20cc0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
20cd0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
20ce0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
20cf0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
20d00 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
20d10 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
20d20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
20d30 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
20d40 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
20d50 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
20d60 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
20d70 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
20d80 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
20d90 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
20da0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
20db0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
20dc0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
20dd0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
20de0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
20df0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
20e00 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
20e10 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
20e20 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
20e30 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
20e40 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
20e50 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
20e60 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
20e70 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
20e80 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
20e90 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
20ea0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
20eb0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
20ec0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
20ed0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
20ee0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
20ef0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
20f00 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
20f10 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
20f20 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
20f30 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
20f40 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
20f50 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
20f60 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
20f70 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
20f80 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
20f90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
20fa0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
20fb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20fc0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
20fd0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20fe0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
20ff0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
21000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21010 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
21020 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
21030 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
21040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
21050 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
21060 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
21070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21080 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
21090 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
210a0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
210b0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
210c0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
210d0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
210e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
210f0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
21100 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
21110 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
21120 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
21130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
21140 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
21150 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
21160 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
21170 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
21180 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
21190 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
211a0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
211b0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
211c0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
211d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
211e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
211f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21200 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
21210 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
21220 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
21230 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
21240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21250 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
21260 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
21270 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
21280 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
21290 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
212a0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
212b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
212c0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
212d0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
212e0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
212f0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
21300 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
21310 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
21320 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
21330 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
21340 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
21350 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
21360 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
21370 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
21380 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
21390 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
213a0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
213b0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
213c0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
213d0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
213e0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
213f0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
21400 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
21410 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
21420 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
21430 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
21440 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
21450 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
21460 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
21470 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
21480 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
21490 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
214a0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
214b0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
214c0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
214d0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
214e0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
214f0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
21500 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
21510 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
21520 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
21530 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
21540 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
21550 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
21560 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
21570 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
21580 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
21590 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
215a0 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
215b0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
215c0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
215d0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
215e0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
215f0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
21600 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
21610 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
21620 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
21630 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
21640 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
21650 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
21660 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
21670 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
21680 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
21690 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
216a0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
216b0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
216c0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
216d0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
216e0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
216f0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
21700 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
21710 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
21720 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
21730 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
21740 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
21750 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
21760 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
21770 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
21780 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
21790 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
217a0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
217b0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
217c0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
217d0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
217e0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
217f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
21800 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
21810 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
21820 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
21830 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
21840 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
21850 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21860 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
21870 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
21880 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
21890 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
218a0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
218b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
218c0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
218d0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
218e0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
218f0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
21900 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
21910 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
21920 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
21930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21940 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
21950 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
21960 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
21970 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
21980 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
21990 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
219a0 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
219b0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
219c0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
219d0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
219e0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
219f0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
21a00 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
21a10 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21a20 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
21a30 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
21a40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21a50 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
21a60 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
21a70 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
21a80 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
21a90 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
21aa0 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
21ab0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
21ac0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
21ad0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
21ae0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
21af0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
21b00 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
21b10 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
21b20 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
21b30 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
21b40 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
21b50 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
21b60 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
21b70 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
21b80 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
21b90 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
21ba0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
21bb0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
21bc0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
21bd0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
21be0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
21bf0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
21c00 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
21c10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21c20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
21c30 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
21c40 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
21c50 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
21c60 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
21c70 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
21c80 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
21c90 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
21ca0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
21cb0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
21cc0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
21cd0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
21ce0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
21cf0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
21d00 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
21d10 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
21d20 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
21d30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21d40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21d50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
21d60 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
21d70 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
21d80 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
21d90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21da0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
21db0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
21dc0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
21dd0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
21de0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
21df0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
21e00 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
21e10 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
21e20 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
21e30 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
21e40 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
21e50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
21e60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
21e70 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
21e80 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
21e90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
21ea0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65  ata_count(P) the
21eb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
21ec0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20  ns in the.** of 
21ed0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
21ee0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21ef0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74  ement] P..*/.int
21f00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
21f10 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21f20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
21f30 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
21f40 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
21f50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
21f60 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
21f70 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
21f80 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
21f90 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
21fa0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
21fb0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
21fc0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
21fd0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
21fe0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
21ff0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
22000 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
22010 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
22020 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
22030 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
22040 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
22050 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
22060 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
22070 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
22080 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
22090 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
220a0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
220b0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
220c0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
220d0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
220e0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
220f0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
22100 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
22110 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
22120 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
22130 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
22140 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
22150 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
22160 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
22170 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
22180 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
22190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
221a0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
221b0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
221c0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
221d0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
221e0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
221f0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
22200 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
22210 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
22220 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
22230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22240 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
22250 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
22260 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
22270 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
22280 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
22290 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
222a0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
222b0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
222c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
222d0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
222e0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
222f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
22300 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
22310 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
22320 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
22330 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22340 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
22350 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
22360 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
22370 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
22380 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
22390 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
223a0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
223b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
223c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
223d0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
223e0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
223f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
22400 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
22410 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
22420 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
22430 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
22440 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
22450 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
22460 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
22470 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
22480 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
22490 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
224a0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
224b0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
224c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
224d0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
224e0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
224f0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
22500 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
22510 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
22520 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
22530 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
22540 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
22550 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
22560 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
22570 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
22580 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
22590 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
225a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
225b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
225c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
225d0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
225e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
225f0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
22600 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
22610 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
22620 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
22630 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
22640 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
22650 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
22660 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
22670 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
22680 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
22690 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
226a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
226b0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
226c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
226d0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
226e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
226f0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
22700 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
22710 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
22720 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22730 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
22740 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
22750 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
22760 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
22770 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
22780 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
22790 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
227a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
227b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
227c0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
227d0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
227e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
227f0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
22800 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
22810 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
22820 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
22830 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
22840 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
22850 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
22860 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
22870 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
22880 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
22890 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
228a0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
228b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
228c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
228d0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
228e0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
228f0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
22900 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
22910 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
22920 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
22930 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
22940 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22950 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
22960 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
22970 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
22980 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
22990 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
229a0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
229b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
229c0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
229d0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
229e0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
229f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
22a00 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
22a10 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
22a20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22a30 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
22a40 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
22a50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
22a60 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
22a70 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
22a80 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
22a90 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
22aa0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
22ab0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
22ac0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
22ad0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
22ae0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
22af0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
22b00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
22b10 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
22b20 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
22b30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22b40 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
22b50 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
22b60 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
22b70 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
22b80 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
22b90 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
22ba0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
22bb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65   string..** ^The
22bc0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22bd0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
22be0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
22bf0 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
22c00 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
22c10 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
22c20 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22c30 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
22c40 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
22c50 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
22c60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22c70 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
22c80 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
22c90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
22ca0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
22cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22cc0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
22cd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
22ce0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
22cf0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
22d00 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
22d10 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
22d20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
22d30 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
22d40 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
22d50 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
22d60 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
22d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
22d80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22d90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
22da0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
22db0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
22dc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
22dd0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
22de0 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
22df0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
22e00 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
22e10 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65  f UTF-8..** ^The
22e20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
22e30 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
22e40 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
22e50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
22e60 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
22e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
22e80 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
22e90 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
22ea0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
22eb0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
22ec0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22ed0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
22ee0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
22ef0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
22f00 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
22f10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
22f20 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
22f30 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
22f40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
22f50 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
22f60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
22f70 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
22f80 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
22f90 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
22fa0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
22fb0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
22fc0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
22fd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22fe0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
22ff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
23000 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
23010 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
23020 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
23030 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
23040 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
23050 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
23060 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
23070 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
23080 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
23090 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
230a0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
230b0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
230c0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
230d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
230e0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
230f0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
23100 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
23110 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
23120 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
23130 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
23140 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
23150 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
23160 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
23170 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
23180 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
23190 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
231a0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
231b0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
231c0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
231d0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
231e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
231f0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
23200 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
23210 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23220 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
23230 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
23240 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
23250 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
23260 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
23270 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
23280 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
23290 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
232a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
232b0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
232c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
232d0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
232e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
232f0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
23300 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
23310 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
23320 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
23330 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
23340 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
23350 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
23360 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
23370 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
23380 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
23390 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
233a0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
233b0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
233c0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
233d0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
233e0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
233f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
23400 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
23410 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
23420 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
23430 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
23440 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
23450 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
23460 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
23470 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
23480 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
23490 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
234a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
234b0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
234c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
234d0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
234e0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
234f0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
23500 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
23510 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
23520 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
23530 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
23540 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
23550 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
23560 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
23570 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
23580 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
23590 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
235a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
235b0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
235c0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
235d0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
235e0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
235f0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
23600 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
23610 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
23620 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
23630 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
23640 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
23650 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
23660 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
23670 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
23680 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
23690 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
236a0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
236b0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
236c0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
236d0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
236e0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
236f0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
23700 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
23710 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
23720 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
23730 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
23740 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
23750 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
23760 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
23770 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
23780 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
23790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
237a0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
237b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
237c0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
237d0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79  lidated..** ^(Ty
237e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
237f0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
23800 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
23810 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
23820 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
23830 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
23840 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
23850 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
23860 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
23870 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
23880 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
23890 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
238a0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
238b0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
238c0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
238d0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
238e0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
238f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
23900 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
23910 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
23920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23930 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
23940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23950 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23960 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
23970 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
23980 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
23990 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
239a0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
239b0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
239c0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
239d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
239e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
239f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23a00 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
23a10 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
23a20 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
23a30 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
23a40 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
23a50 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
23a60 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
23a70 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
23a80 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
23a90 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
23aa0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
23ab0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
23ac0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
23ad0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
23ae0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
23af0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
23b00 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
23b10 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
23b20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
23b30 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
23b40 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
23b50 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
23b60 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
23b70 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
23b80 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
23b90 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
23ba0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
23bb0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
23bc0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  lidated..**.** ^
23bd0 28 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20  (The safest and 
23be0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
23bf0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
23c00 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
23c10 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
23c20 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23c30 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
23c40 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
23c50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23c60 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
23c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23c80 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
23c90 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
23ca0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
23cb0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
23cc0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
23cd0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
23ce0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
23cf0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
23d00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23d10 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
23d20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  >)^.**.** In oth
23d30 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
23d40 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
23d50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
23d60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
23d70 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
23d80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23d90 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
23da0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
23db0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
23dc0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
23dd0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
23de0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
23df0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
23e00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23e10 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
23e20 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
23e30 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
23e40 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
23e50 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
23e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23e70 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
23e80 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23e90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
23ea0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
23eb0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23ec0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
23ed0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
23ee0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23ef0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
23f00 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
23f10 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
23f20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
23f30 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
23f40 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
23f50 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
23f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23f70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
23f80 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
23f90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23fa0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
23fb0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
23fc0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
23fd0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
23fe0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
23ff0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
24000 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
24010 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
24020 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
24030 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
24040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24050 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
24060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
24070 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
24080 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
24090 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
240a0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
240b0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
240c0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
240d0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
240e0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
240f0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
24100 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
24110 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
24120 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
24130 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
24140 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
24150 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
24160 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
24170 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
24180 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
24190 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
241a0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
241b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
241c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
241d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
241e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
241f0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
24200 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24210 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
24220 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
24230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24240 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
24250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
24260 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
24270 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
24280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
24290 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
242a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
242b0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
242c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
242d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
242e0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
242f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
24300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24310 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
24320 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
24330 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
24340 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
24350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24360 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
24370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
24380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24390 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
243a0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
243b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
243c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
243d0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
243e0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
243f0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
24400 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
24410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24420 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
24430 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
24440 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
24450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74  .** ^If the stat
24470 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
24480 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
24490 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
244a0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
244b0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
244c0 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75  urned. ^If execu
244d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
244e0 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
244f0 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
24500 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
24510 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
24520 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24530 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
24540 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
24550 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
24560 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
24570 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
24580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
24590 5e 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20  ^If the virtual 
245a0 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
245b0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
245c0 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
245d0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
245e0 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
245f0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
24600 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
24610 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
24620 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
24630 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20  .** ^Incomplete 
24640 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
24650 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
24660 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
24670 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
24680 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
24690 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
246a0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
246b0 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
246c0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
246d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
246e0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
246f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
24700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24710 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
24720 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
24730 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
24740 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
24750 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
24760 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
24770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
24780 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
24790 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
247a0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
247b0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
247c0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
247d0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
247e0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
247f0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
24800 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
24810 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
24820 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
24830 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
24840 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
24850 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
24860 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
24870 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
24880 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
24890 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
248a0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
248b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
248c0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
248d0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
248e0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
248f0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
24900 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
24910 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24920 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
24930 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24940 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
24950 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
24960 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
24970 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
24980 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
24990 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
249a0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
249b0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
249c0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
249d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
249e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
249f0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
24a00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
24a10 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
24a20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24a30 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
24a40 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
24a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
24a60 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
24a70 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
24a80 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
24a90 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
24aa0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
24ab0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
24ac0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
24ad0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
24ae0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
24af0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
24b00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24b10 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
24b20 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
24b30 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b50 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
24b60 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
24b70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
24b80 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
24b90 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
24ba0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
24bb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24bc0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
24bd0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
24be0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24bf0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
24c00 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e  * ^These two fun
24c10 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
24c20 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
24c30 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
24c40 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
24c50 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
24c60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
24c70 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
24c80 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
24c90 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
24ca0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
24cb0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
24cc0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
24cd0 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
24ce0 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68  the.** two is th
24cf0 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  at the second pa
24d00 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d  rameter, the nam
24d10 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
24d20 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  ) function or.**
24d30 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65   aggregate, is e
24d40 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20  ncoded in UTF-8 
24d50 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
24d60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
24d70 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20  d UTF-16.** for 
24d80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24d90 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  unction16()..**.
24da0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
24db0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
24dc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24dd0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
24de0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
24df0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
24e00 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
24e10 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
24e20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
24e30 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
24e40 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
24e50 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
24e60 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
24e70 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
24e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24e90 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
24ea0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
24eb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24ec0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
24ed0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
24ee0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
24ef0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
24f00 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
24f10 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
24f20 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
24f30 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
24f40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
24f50 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
24f60 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
24f70 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
24f80 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
24f90 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  .  ^Any attempt 
24fa0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
24fb0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
24fc0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
24fd0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
24fe0 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
24ff0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
25000 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
25010 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
25020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
25030 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
25040 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
25050 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
25060 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
25070 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
25080 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
25090 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
250a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
250b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
250c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
250d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
250e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
250f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
25100 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25110 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
25120 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
25130 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
25140 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
25150 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
25160 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
25170 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
25180 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25190 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
251a0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
251b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
251c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
251d0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
251e0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
251f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
25200 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
25210 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
25220 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
25230 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
25240 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
25250 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
25260 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
25270 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
25280 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
25290 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
252a0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
252b0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
252c0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
252d0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
252e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
252f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
25300 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
25310 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
25320 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
25330 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
25340 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
25350 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
25360 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
25370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
25380 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
25390 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
253a0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
253b0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
253c0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
253d0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
253e0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
253f0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
25400 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
25410 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
25420 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
25430 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
25440 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
25450 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
25460 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
25470 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
25480 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
25490 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
254a0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
254b0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
254c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
254d0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
254e0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
254f0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
25500 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
25510 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
25520 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
25530 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
25540 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
25550 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
25560 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
25570 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
25580 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
25590 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
255a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
255b0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
255c0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
255d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
255e0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
255f0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
25600 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
25610 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
25620 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
25630 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
25640 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
25650 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
25660 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
25670 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
25680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
25690 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
256a0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
256b0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
256c0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
256d0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
256e0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
256f0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
25700 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
25710 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
25720 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
25730 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
25740 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
25750 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
25760 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25770 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
25780 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
25790 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
257a0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
257b0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
257c0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
257d0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
257e0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
257f0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
25800 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
25810 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
25820 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
25830 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
25840 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
25850 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
25860 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
25870 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
25880 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
25890 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
258a0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
258b0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
258c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
258d0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
258e0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
258f0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
25900 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
25910 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
25920 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
25930 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
25940 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
25950 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
25960 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
25970 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
25980 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
25990 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
259a0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
259b0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
259c0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
259d0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
259e0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
259f0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
25a00 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
25a10 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
25a20 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
25a30 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
25a40 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
25a50 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
25a60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25a70 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
25a80 20 5e 54 68 65 20 66 69 72 73 74 20 61 70 70 6c   ^The first appl
25a90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25aa0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25ab0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
25ac0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
25ad0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
25ae0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
25af0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25b00 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
25b10 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75  ame..** ^Subsequ
25b20 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
25b30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25b40 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
25b50 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
25b60 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
25b70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
25b80 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
25b90 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
25ba0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
25bb0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
25bc0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
25bd0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
25be0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
25bf0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
25c00 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
25c10 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
25c20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
25c30 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
25c40 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
25c50 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
25c60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25c70 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
25c80 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
25c90 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
25ca0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
25cb0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
25cc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25cd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25ce0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25cf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25d00 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
25d10 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
25d20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
25d30 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
25d40 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
25d50 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25d60 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
25d70 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
25d80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
25d90 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
25da0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
25db0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
25dc0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
25dd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25de0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
25df0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
25e00 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
25e10 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
25e20 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
25e30 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
25e40 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
25e50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25e60 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25e70 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
25e80 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
25e90 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25ea0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
25eb0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
25ec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
25ed0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
25ee0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
25ef0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
25f00 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
25f10 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
25f20 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
25f30 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
25f40 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
25f50 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
25f60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
25f70 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
25f80 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25f90 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
25fa0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
25fb0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
25fc0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
25fd0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
25fe0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
25ff0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
26000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
26010 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
26020 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
26030 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26040 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
26050 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
26060 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
26070 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
26080 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
26090 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
260a0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
260b0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
260c0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
260d0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
260e0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
260f0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
26100 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
26110 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
26120 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
26130 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
26140 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
26150 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
26160 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
26170 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
26180 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
26190 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
261a0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
261b0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
261c0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
261d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
261e0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
261f0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
26200 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
26210 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
26220 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
26230 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
26240 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
26250 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
26260 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
26270 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
26280 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
26290 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
262a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
262b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
262c0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
262d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
262e0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
262f0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
26300 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
26310 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
26320 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
26330 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
26340 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
26350 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
26360 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
26370 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
26380 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
26390 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
263a0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
263b0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
263c0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
263d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
263e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
263f0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
26400 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
26410 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
26420 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
26430 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
26440 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
26450 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
26460 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
26470 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
26480 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
26490 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
264a0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
264b0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
264c0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
264d0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
264e0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
264f0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
26500 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26510 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
26520 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26530 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
26540 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
26550 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
26560 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
26570 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
26580 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
26590 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
265a0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
265b0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
265c0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
265d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
265e0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
265f0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
26600 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
26610 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
26620 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
26630 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
26640 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
26650 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
26660 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
26670 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26680 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
26690 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
266a0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
266b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
266c0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
266d0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
266e0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
266f0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
26700 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26710 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
26720 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
26730 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
26740 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
26750 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
26760 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
26770 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
26780 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
26790 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
267a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
267b0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
267c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
267d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
267e0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
267f0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
26800 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
26810 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
26820 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
26830 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
26840 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
26850 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
26860 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
26870 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
26880 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
26890 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
268a0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
268b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
268c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
268d0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
268e0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
268f0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
26900 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
26910 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
26920 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
26930 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
26940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
26950 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
26960 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
26970 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
26980 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
26990 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
269a0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
269b0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
269c0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
269d0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
269e0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
269f0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
26a00 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
26a10 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
26a20 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
26a30 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
26a40 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
26a50 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
26a60 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
26a70 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
26a80 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
26a90 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
26aa0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
26ab0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
26ac0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
26ad0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
26ae0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
26af0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
26b00 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
26b10 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
26b20 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
26b30 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
26b40 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
26b50 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
26b60 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
26b70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
26b80 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
26b90 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
26ba0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
26bb0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
26bc0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
26bd0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
26be0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
26bf0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26c00 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
26c10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26c20 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
26c30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26c40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
26c50 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
26c60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
26c70 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
26c80 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
26c90 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
26ca0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
26cb0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
26cc0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
26cd0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
26ce0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
26cf0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26d00 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
26d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
26d30 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
26d40 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
26d50 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
26d60 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
26d70 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
26d80 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
26d90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
26da0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
26db0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
26dc0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26dd0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
26de0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
26df0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
26e00 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26e10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26e20 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
26e30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
26e40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26e50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
26e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26e70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26e80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26e90 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
26ea0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
26eb0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
26ec0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
26ed0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
26ee0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
26ef0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
26f00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26f10 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
26f20 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
26f30 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 69  **.** Implementi
26f40 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
26f50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
26f60 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
26f70 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
26f80 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
26f90 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
26fa0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
26fb0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
26fc0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
26fd0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
26fe0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
26ff0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
27000 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
27010 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
27020 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
27030 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
27040 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
27050 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
27060 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
27070 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
27080 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
27090 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
270a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
270b0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
270c0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
270d0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
270e0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
270f0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
27100 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
27110 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
27120 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
27130 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
27140 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
27150 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
27160 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
27170 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
27180 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
27190 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
271a0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
271b0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
271c0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
271d0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
271e0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
271f0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
27200 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
27210 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
27220 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
27230 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
27240 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
27250 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
27260 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27270 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
27280 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
27290 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
272a0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
272b0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
272c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
272d0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
272e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
272f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
27300 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
27310 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
27320 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
27330 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
27340 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
27350 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
27360 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
27370 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
27380 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
27390 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
273a0 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
273b0 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
273c0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
273d0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
273e0 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
273f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
27400 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
27410 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
27420 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
27430 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
27440 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
27450 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
27460 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
27470 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
27480 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
27490 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
274a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
274b0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
274c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
274d0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
274e0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
274f0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
27500 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27510 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
27520 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
27530 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
27540 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
27550 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
27560 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
27570 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
27580 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
27590 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
275a0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
275b0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
275c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
275d0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
275e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
275f0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
27600 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
27610 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
27620 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
27630 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
27640 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27650 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
27660 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
27670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27680 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
27690 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
276a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
276b0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
276c0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
276d0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
276e0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
276f0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
27700 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
27710 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
27720 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
27730 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
27740 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
27750 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27760 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
27770 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
27780 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
27790 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
277a0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
277b0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
277c0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
277d0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
277e0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
277f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27800 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27810 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
27820 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
27830 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
27840 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
27850 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
27860 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
27870 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
27880 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27890 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
278a0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
278b0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
278c0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
278d0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
278e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
278f0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
27900 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
27910 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27920 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
27930 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27940 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
27950 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
27960 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
27970 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
27980 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
27990 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
279a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
279b0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
279c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
279d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
279e0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
279f0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
27a00 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
27a10 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
27a20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
27a30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
27a40 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
27a50 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
27a60 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
27a70 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
27a80 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
27a90 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
27aa0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
27ab0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
27ac0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
27ad0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
27ae0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
27af0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
27b00 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
27b10 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
27b20 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
27b30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
27b40 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
27b50 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
27b60 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
27b70 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
27b80 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
27b90 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
27ba0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
27bb0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
27bc0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
27bd0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
27be0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
27bf0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
27c00 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
27c10 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
27c20 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
27c30 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
27c40 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
27c50 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
27c60 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
27c70 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
27c80 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
27c90 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
27ca0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
27cb0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
27cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27cd0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27ce0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27cf0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27d00 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
27d10 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
27d20 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
27d30 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
27d40 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
27d50 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
27d60 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
27d70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27d80 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74  tion. ^If no met
27d90 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
27da0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
27db0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
27dc0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
27dd0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
27de0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
27df0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
27e00 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
27e10 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
27e20 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
27e30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
27e40 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
27e50 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
27e60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
27e70 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27e80 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
27e90 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
27ea0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
27eb0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
27ec0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
27ed0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
27ee0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
27ef0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27f00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27f10 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
27f20 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
27f30 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
27f40 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
27f50 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
27f60 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
27f70 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20  stroyed..** ^If 
27f80 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
27f90 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
27fa0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
27fb0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
27fc0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
27fd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27fe0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27ff0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
28000 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
28010 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
28020 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
28030 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
28040 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
28050 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
28060 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
28070 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
28080 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
28090 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
280a0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
280b0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
280c0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
280d0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
280e0 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20  ime.  ^The only 
280f0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
28100 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
28110 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
28120 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
28130 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
28140 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
28150 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
28160 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
28170 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
28180 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
28190 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
281a0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
281b0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
281c0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
281d0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
281e0 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a  parameters].)^.*
281f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
28200 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
28210 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
28220 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
28230 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
28240 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
28250 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
28260 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
28270 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28280 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
28290 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
282a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
282b0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
282c0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
282d0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
282e0 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
282f0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
28300 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
28310 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
28320 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
28330 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
28340 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
28350 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
28360 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
28370 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
28380 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
28390 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
283a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
283b0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
283c0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
283d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
283e0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
283f0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
28400 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
28410 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
28420 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
28430 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
28440 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
28450 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
28460 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
28470 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
28480 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
28490 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
284a0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
284b0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
284c0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
284d0 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
284e0 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
284f0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
28500 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
28510 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
28520 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
28530 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
28540 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
28550 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
28560 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
28570 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
28580 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
28590 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
285a0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
285b0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
285c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
285d0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
285e0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
285f0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
28600 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
28610 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
28620 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
28630 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
28640 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
28650 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
28660 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
28670 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
28680 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
28690 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
286a0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
286b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
286c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
286d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
286e0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
286f0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
28700 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
28710 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
28720 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
28730 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
28740 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
28750 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
28760 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
28770 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
28780 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
28790 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
287a0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
287b0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
287c0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
287d0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
287e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
287f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
28800 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
28810 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
28820 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
28830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28840 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
28850 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
28860 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
28870 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
28880 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
28890 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
288a0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
288b0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
288c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
288d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
288e0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
288f0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
28900 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
28910 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28920 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28930 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
28940 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
28950 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
28960 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
28970 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
28980 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
28990 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
289a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
289b0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
289c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
289d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
289e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
289f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28a00 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
28a10 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
28a20 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
28a30 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
28a40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28a50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28a60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
28a70 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
28a80 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
28a90 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
28aa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
28ab0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
28ac0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
28ad0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
28ae0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
28af0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
28b00 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
28b10 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
28b20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28b30 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
28b40 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
28b50 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
28b60 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
28b70 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
28b80 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
28b90 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
28ba0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
28bb0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
28bc0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
28bd0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
28be0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
28bf0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
28c00 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
28c10 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
28c20 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
28c30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28c40 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
28c50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28c60 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
28c70 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
28c80 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
28c90 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
28ca0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
28cb0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
28cc0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
28cd0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
28ce0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28cf0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
28d00 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
28d10 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
28d20 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
28d30 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
28d40 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
28d50 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
28d60 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
28d70 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
28d80 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28d90 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28da0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28db0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
28dc0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
28dd0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
28de0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
28df0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28e00 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
28e10 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
28e20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
28e30 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
28e40 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
28e50 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
28e60 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
28e70 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
28e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28e90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
28ea0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
28eb0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
28ec0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
28ed0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
28ee0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
28ef0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
28f00 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
28f10 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
28f20 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
28f30 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
28f40 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
28f50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28f60 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
28f70 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28f80 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
28f90 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
28fa0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
28fb0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28fc0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
28fd0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
28fe0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
28ff0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
29000 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
29010 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
29020 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
29030 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29040 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
29050 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
29060 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
29070 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
29080 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
29090 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
290a0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
290b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
290c0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
290d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
290e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
290f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29100 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29110 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
29120 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29130 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
29140 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
29150 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
29160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
29170 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
29180 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
29190 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
291a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
291b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
291c0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
291d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
291e0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
291f0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
29200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29210 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
29220 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29230 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
29240 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
29250 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29260 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29270 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
29280 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29290 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
292a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
292b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
292c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
292d0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
292e0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
292f0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
29300 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
29310 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29320 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29330 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
29340 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
29350 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
29360 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
29370 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29380 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
29390 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
293a0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
293b0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
293c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
293d0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
293e0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
293f0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
29400 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
29410 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
29420 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
29430 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
29440 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
29450 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29460 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29470 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
29480 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
29490 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
294a0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
294b0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
294c0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
294d0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
294e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
294f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
29500 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29510 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29520 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
29530 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
29540 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
29550 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
29560 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
29570 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
29580 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
29590 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
295a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
295b0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
295c0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
295d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
295e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
295f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29600 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
29610 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
29620 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
29630 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
29640 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
29650 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
29660 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
29670 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
29680 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
29690 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
296a0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
296b0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
296c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
296d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
296e0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
296f0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
29700 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
29710 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
29720 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
29730 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
29740 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
29750 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
29760 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
29770 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
29780 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
29790 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
297a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
297b0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
297c0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
297d0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
297e0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
297f0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
29800 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
29810 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
29820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29830 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
29840 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29850 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
29860 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
29870 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
29880 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
29890 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
298a0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
298b0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
298c0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
298d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
298e0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
298f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29900 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29910 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29920 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
29930 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
29940 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29950 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
29960 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
29970 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29980 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
29990 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
299a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
299b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
299c0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
299d0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
299e0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
299f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
29a00 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
29a10 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
29a20 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
29a30 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
29a40 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
29a50 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
29a60 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
29a70 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
29a80 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
29a90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29aa0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
29ab0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
29ac0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
29ad0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29ae0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29af0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
29b00 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
29b10 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
29b20 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
29b30 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
29b40 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
29b50 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
29b60 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
29b70 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
29b80 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
29b90 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
29ba0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
29bb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29bc0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
29bd0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
29be0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
29bf0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
29c00 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29c10 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
29c20 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29c30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29c40 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
29c50 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
29c60 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
29c70 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
29c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29c90 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
29ca0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29cb0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
29cc0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
29cd0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
29ce0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29cf0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
29d00 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
29d10 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
29d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29d30 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
29d40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
29d50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29d60 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
29d70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29d80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29d90 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
29da0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
29db0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
29dc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29dd0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
29de0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
29df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29e00 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
29e10 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
29e20 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
29e30 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
29e40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
29e50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29e60 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
29e70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29e80 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
29e90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29ea0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29eb0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
29ec0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29ed0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
29ee0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29ef0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29f00 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
29f10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29f20 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
29f30 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29f40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29f50 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
29f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29f70 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
29f80 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
29f90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29fa0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
29fb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
29fc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
29fd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
29fe0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
29ff0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2a000 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
2a010 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
2a020 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
2a030 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ences.**.** Thes
2a040 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2a050 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
2a060 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2a070 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64  ces to the.** [d
2a080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a090 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
2a0a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2a0b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2a0c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
2a0d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2a0e0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
2a0f0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
2a100 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
2a110 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a120 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
2a130 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2a140 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
2a150 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
2a160 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a170 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e  collation16(). ^
2a180 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
2a190 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
2a1a0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
2a1b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2a1c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  nt..**.** ^The t
2a1d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
2a1e0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
2a1f0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
2a200 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
2a210 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
2a220 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2a230 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2a240 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
2a250 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
2a260 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
2a270 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
2a280 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
2a290 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
2a2a0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
2a2b0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2a2c0 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
2a2d0 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a  pectively. ^The.
2a2e0 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
2a2f0 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
2a300 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74  [SQLITE_UTF16] t
2a310 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
2a320 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65  the routine.** e
2a330 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
2a340 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72  to be UTF-16 str
2a350 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69  ings in the nati
2a360 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f  ve byte order, o
2a370 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  r the.** argumen
2a380 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45  t can be [SQLITE
2a390 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
2a3a0 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f  if the.** the ro
2a3b0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
2a3c0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
2a3d0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
2a3e0 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
2a3f0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
2a400 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
2a410 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
2a420 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
2a430 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
2a440 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2a450 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
2a460 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55  t.  ^If it is NU
2a470 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
2a480 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
2a490 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2a4a0 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
2a4b0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
2a4c0 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
2a4d0 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d  e)..** ^Each tim
2a4e0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
2a4f0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
2a500 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
2a510 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
2a520 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
2a530 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
2a540 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
2a550 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
2a560 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
2a570 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a580 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
2a590 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a5a0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
2a5b0 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20   ^The remaining 
2a5c0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2a5d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
2a5e0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
2a5f0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
2a600 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
2a610 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
2a620 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
2a630 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
2a640 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
2a650 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
2a660 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2a670 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
2a680 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
2a690 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
2a6a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2a6b0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
2a6c0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
2a6d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
2a6e0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
2a6f0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
2a700 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
2a710 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
2a720 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
2a730 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
2a740 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
2a750 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
2a760 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
2a770 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2a780 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
2a790 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
2a7a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a7b0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
2a7c0 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
2a7d0 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
2a7e0 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
2a7f0 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
2a800 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65  lation.  ^The de
2a810 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2a820 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
2a830 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
2a840 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
2a850 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
2a860 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a870 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
2a880 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
2a890 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2a8a0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f  ion_v2()..** ^Co
2a8b0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
2a8c0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
2a8d0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
2a8e0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
2a8f0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
2a900 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
2a910 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
2a920 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a930 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
2a940 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2a950 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
2a960 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2a970 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a980 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2a990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2a9a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2a9b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2a9c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a9d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2a9e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a9f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2aa00 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2aa10 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2aa20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2aa30 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2aa40 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2aa50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2aa60 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2aa70 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2aa80 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2aa90 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2aaa0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2aab0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2aac0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2aad0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
2aae0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2aaf0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
2ab00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ab10 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2ab20 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2ab30 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2ab40 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2ab50 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2ab60 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2ab70 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2ab80 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2ab90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2aba0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
2abb0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
2abc0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
2abd0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
2abe0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
2abf0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
2ac00 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2ac10 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
2ac20 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
2ac30 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
2ac40 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
2ac50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2ac60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
2ac70 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2ac80 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
2ac90 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2aca0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
2acb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2acc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
2acd0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
2ace0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2acf0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
2ad00 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
2ad10 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
2ad20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
2ad30 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2ad40 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
2ad50 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
2ad60 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
2ad70 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2ad80 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
2ad90 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
2ada0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2adb0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
2adc0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
2add0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
2ade0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
2adf0 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
2ae00 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
2ae10 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2ae20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
2ae30 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2ae40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2ae50 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2ae60 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2ae70 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2ae80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2ae90 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2aea0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2aeb0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2aec0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2aed0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2aee0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2aef0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
2af00 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2af10 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
2af20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2af30 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2af40 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
2af50 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
2af60 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
2af70 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2af80 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
2af90 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
2afa0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2afb0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2afc0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2afd0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2afe0 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
2aff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2b000 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
2b010 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
2b020 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
2b030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2b040 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
2b050 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2b060 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
2b070 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2b080 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b090 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
2b0a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2b0b0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2b0c0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2b0d0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2b0e0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2b0f0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2b100 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2b110 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b120 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2b130 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2b140 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2b150 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2b160 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2b170 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
2b180 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
2b190 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
2b1a0 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
2b1b0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
2b1c0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
2b1d0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
2b1e0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
2b1f0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
2b200 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
2b210 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
2b220 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
2b230 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
2b240 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
2b250 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
2b260 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
2b270 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2b280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2b290 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2b2a0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2b2b0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2b2c0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
2b2d0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2b2e0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
2b2f0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
2b300 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
2b310 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
2b320 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
2b330 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
2b340 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
2b350 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
2b360 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
2b370 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
2b380 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
2b390 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2b3a0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2b3b0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2b3c0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2b3d0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2b3e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2b3f0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
2b400 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2b410 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2b420 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2b430 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2b440 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2b450 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
2b460 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2b470 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2b480 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2b490 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
2b4a0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
2b4b0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
2b4c0 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
2b4d0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2b4e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2b4f0 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
2b500 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
2b510 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
2b520 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
2b530 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
2b540 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
2b550 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
2b560 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
2b570 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
2b580 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
2b590 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2b5a0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2b5b0 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
2b5c0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
2b5d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
2b5e0 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
2b5f0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2b600 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2b610 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2b620 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2b630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b640 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
2b650 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
2b660 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  me.**.** ^The sq
2b670 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
2b680 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
2b690 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
2b6a0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
2b6b0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
2b6c0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
2b6d0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
2b6e0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
2b6f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2b700 20 5e 49 66 20 74 68 65 20 6f 70 65 72 61 74 69   ^If the operati
2b710 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
2b720 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
2b730 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
2b740 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
2b750 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
2b760 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
2b770 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
2b780 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
2b790 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e  t second. ^The n
2b7a0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2b7b0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
2b7c0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
2b7d0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
2b7e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
2b7f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2b800 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
2b810 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2b820 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2b830 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2b840 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2b850 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2b860 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  s] object..*/.in
2b870 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
2b880 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2b890 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
2b8a0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
2b8b0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
2b8c0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
2b8d0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
2b8e0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
2b8f0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
2b900 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
2b910 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
2b920 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
2b930 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
2b940 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
2b950 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
2b960 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
2b970 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
2b980 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
2b990 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
2b9a0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
2b9b0 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
2b9c0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
2b9d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2b9e0 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
2b9f0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
2ba00 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
2ba10 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
2ba20 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
2ba30 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
2ba40 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
2ba50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
2ba60 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
2ba70 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
2ba80 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
2ba90 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2baa0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2bab0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
2bac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bad0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
2bae0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2baf0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
2bb00 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
2bb10 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
2bb20 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2bb30 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
2bb40 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
2bb50 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
2bb60 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
2bb70 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2bb80 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
2bb90 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
2bba0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2bbb0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
2bbc0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
2bbd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2bbe0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2bbf0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
2bc00 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
2bc10 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
2bc20 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
2bc30 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2bc40 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2bc50 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
2bc60 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
2bc70 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2bc80 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
2bc90 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
2bca0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
2bcb0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2bcc0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
2bcd0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
2bce0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
2bcf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2bd00 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
2bd10 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
2bd20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
2bd30 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2bd40 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
2bd50 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
2bd60 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
2bd70 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
2bd80 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
2bd90 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
2bda0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2bdb0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2bdc0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2bdd0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
2bde0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
2bdf0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2be00 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
2be10 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
2be20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
2be30 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
2be40 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
2be50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2be60 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
2be70 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
2be80 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
2be90 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
2bea0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2beb0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
2bec0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2bed0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
2bee0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
2bef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2bf00 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
2bf10 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
2bf20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
2bf30 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
2bf40 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
2bf50 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
2bf60 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2bf70 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
2bf80 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
2bf90 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2bfa0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
2bfb0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
2bfc0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
2bfd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
2bfe0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
2bff0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
2c000 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
2c010 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
2c020 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
2c030 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
2c040 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
2c050 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
2c060 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2c070 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
2c080 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
2c090 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
2c0a0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
2c0b0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
2c0c0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
2c0d0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
2c0e0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
2c0f0 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
2c100 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2c110 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
2c120 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
2c130 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
2c140 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
2c150 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
2c160 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
2c170 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
2c180 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
2c190 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2c1a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
2c1b0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
2c1c0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
2c1d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2c1e0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2c1f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c200 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2c210 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
2c220 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
2c230 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
2c240 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
2c250 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2c260 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c270 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
2c280 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2c290 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c2a0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2c2b0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
2c2c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c2d0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
2c2e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c2f0 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
2c300 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
2c310 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
2c320 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2c330 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
2c340 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
2c350 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
2c360 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c370 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
2c380 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
2c390 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
2c3a0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
2c3b0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
2c3c0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
2c3d0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2c3e0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2c3f0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2c400 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2c410 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
2c420 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
2c430 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2c440 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2c450 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
2c460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c470 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
2c480 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
2c490 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2c4a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
2c4b0 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73  b.  ^If pStmt is
2c4c0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
2c4d0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2c4e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c4f0 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
2c500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2c510 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2c520 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
2c530 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
2c540 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20  ^If no prepared 
2c550 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
2c560 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
2c570 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
2c580 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
2c590 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
2c5a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2c5b0 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
2c5c0 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
2c5d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
2c5e0 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
2c5f0 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
2c600 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2c610 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
2c620 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
2c630 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
2c640 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
2c650 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
2c660 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
2c670 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
2c680 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2c6a0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
2c6b0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
2c6c0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2c6d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
2c6e0 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
2c6f0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2c700 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2c710 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2c720 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2c730 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f  ansaction is [CO
2c740 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64  MMIT | committed
2c750 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2c760 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2c770 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2c780 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2c790 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2c7a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2c7b0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2c7c0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73  idden..** ^The s
2c7d0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2c7e0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2c7f0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2c800 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2c810 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2c820 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2c830 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
2c840 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
2c850 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  k]..** ^Any call
2c860 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2c870 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
2c880 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2c890 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2c8a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2c8b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2c8c0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2c8d0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
2c8e0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
2c8f0 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
2c900 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  k..** ^If the ca
2c910 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
2c920 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
2c930 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2c940 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
2c950 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
2c960 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
2c970 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ck..**.** ^The s
2c980 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2c990 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71  ok(D,C,P) and sq
2c9a0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2c9b0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
2c9c0 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ions.** return t
2c9d0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
2c9e0 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2c9f0 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65  call of the same
2ca00 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20   function.** on 
2ca10 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2ca20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2ca30 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
2ca40 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2ca50 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f  for each functio
2ca60 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68  n on D..**.** Th
2ca70 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65  e callback imple
2ca80 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
2ca90 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
2caa0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
2cab0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2cac0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2cad0 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  invoked the call
2cae0 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  back.  Any actio
2caf0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
2cb00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2cb10 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
2cb20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
2cb30 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
2cb40 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
2cb50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2cb60 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
2cb70 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a  ed the commit.**
2cb80 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f   or rollback hoo
2cb90 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  k in the first p
2cba0 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  lace..** Note th
2cbb0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
2cbc0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2cbd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
2cbe0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
2cbf0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
2cc00 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
2cc10 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
2cc20 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
2cc30 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
2cc40 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
2cc50 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
2cc60 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
2cc70 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
2cc80 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
2cc90 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
2cca0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
2ccb0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
2ccc0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
2ccd0 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
2cce0 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
2ccf0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
2cd00 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2cd10 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
2cd20 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
2cd30 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
2cd40 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
2cd50 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
2cd60 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
2cd70 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
2cd80 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
2cd90 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
2cda0 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
2cdb0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
2cdc0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
2cdd0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
2cde0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
2cdf0 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
2ce00 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
2ce10 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
2ce20 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
2ce30 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
2ce40 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
2ce50 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
2ce60 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
2ce70 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
2ce80 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
2ce90 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
2cea0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
2ceb0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
2cec0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
2ced0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
2cee0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2cef0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
2cf00 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
2cf10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
2cf20 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  losed..** ^The r
2cf30 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2cf40 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2cf50 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2cf60 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
2cf70 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
2cf80 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
2cf90 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
2cfa0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2cfb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2cfc0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2cfd0 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
2cfe0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2cff0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
2d000 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
2d010 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
2d020 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2d030 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
2d040 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
2d050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d060 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
2d070 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2d080 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
2d090 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2d0a0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2d0b0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2d0c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
2d0d0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2d0e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d0f0 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
2d100 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2d110 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
2d120 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
2d130 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2d140 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2d150 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
2d160 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2d170 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
2d180 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2d190 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d1a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d1b0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d1c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2d1d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2d1e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2d1f0 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2d200 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2d210 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2d220 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2d230 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2d240 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2d250 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
2d260 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2d270 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2d280 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2d290 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
2d2a0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
2d2b0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2d2c0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
2d2d0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
2d2e0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2d2f0 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
2d300 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
2d310 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
2d320 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
2d330 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
2d340 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
2d350 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2d360 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
2d370 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
2d380 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
2d390 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
2d3a0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
2d3b0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
2d3c0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
2d3d0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
2d3e0 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
2d3f0 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
2d400 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
2d410 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2d420 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2d430 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2d440 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2d450 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
2d460 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
2d470 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
2d480 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
2d490 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
2d4a0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
2d4b0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
2d4c0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
2d4d0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
2d4e0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2d4f0 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2d500 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2d510 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2d520 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2d530 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2d540 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2d550 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2d560 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2d570 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
2d580 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2d590 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
2d5a0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
2d5b0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
2d5c0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
2d5d0 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
2d5e0 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
2d5f0 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
2d600 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
2d610 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
2d620 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2d630 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2d640 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2d650 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2d660 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2d670 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2d680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d690 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2d6a0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2d6b0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2d6c0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2d6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d6e0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2d6f0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2d700 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2d710 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2d720 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2d730 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2d740 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2d750 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2d760 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d770 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2d780 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2d790 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2d7a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2d7b0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2d7c0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2d7d0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2d7e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d7f0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
2d800 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
2d810 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
2d820 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2d830 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
2d840 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2d850 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d860 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2d870 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2d880 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
2d890 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2d8a0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2d8b0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
2d8c0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2d8d0 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
2d8e0 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
2d8f0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2d900 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2d910 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
2d920 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
2d930 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
2d940 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
2d950 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
2d960 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2d970 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
2d980 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
2d990 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2d9a0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
2d9b0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2d9c0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
2d9d0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
2d9e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2d9f0 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
2da00 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
2da10 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
2da20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2da30 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
2da40 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2da50 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
2da60 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
2da70 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2da80 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
2da90 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2daa0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
2dab0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
2dac0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2dad0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
2dae0 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
2daf0 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
2db00 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
2db10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
2db20 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
2db30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2db40 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
2db50 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2db60 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
2db70 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
2db80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
2db90 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
2dba0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
2dbb0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
2dbc0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
2dbd0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2dbe0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2dbf0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2dc00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
2dc10 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
2dc20 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
2dc30 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
2dc40 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
2dc50 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
2dc60 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
2dc70 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
2dc80 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
2dc90 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2dca0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
2dcb0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
2dcc0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
2dcd0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
2dce0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2dcf0 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
2dd00 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
2dd10 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
2dd20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2dd30 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2dd40 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2dd50 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2dd60 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2dd70 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2dd80 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2dd90 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2dda0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2ddb0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2ddc0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2ddd0 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2dde0 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2ddf0 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
2de00 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2de10 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
2de20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2de30 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
2de40 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
2de50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2de60 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2de70 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2de80 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
2de90 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
2dea0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
2deb0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
2dec0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
2ded0 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
2dee0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2def0 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
2df00 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
2df10 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
2df20 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
2df30 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
2df40 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
2df50 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
2df60 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
2df70 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
2df80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2df90 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
2dfa0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
2dfb0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
2dfc0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
2dfd0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
2dfe0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2dff0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2e000 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2e010 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
2e020 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
2e030 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
2e040 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2e050 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
2e060 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
2e070 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
2e080 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
2e090 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
2e0a0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
2e0b0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66  y SQLite..** ^If
2e0c0 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c   an internal all
2e0d0 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  ocation is reque
2e0e0 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20  sted that would 
2e0f0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f  exceed the.** so
2e100 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b  ft heap limit, [
2e110 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2e120 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76  memory()] is inv
2e130 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d  oked one or.** m
2e140 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
2e150 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
2e160 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
2e170 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  ation is perform
2e180 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c  ed..**.** ^The l
2e190 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2e1a0 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66  soft" because if
2e1b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2e1c0 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63  e_memory()].** c
2e1d0 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69  annot free suffi
2e1e0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
2e1f0 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
2e200 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
2e210 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65  eeded,.** the me
2e220 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
2e230 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
2e240 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
2e250 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
2e260 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f  ** ^A negative o
2e270 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2e280 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2e290 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2e2a0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2e2b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2e2c0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2e2d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2e2e0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2e2f0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  xhausted..** ^Th
2e300 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2e310 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2e320 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2e330 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
2e340 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
2e350 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
2e360 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2e370 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20  ..** But if the 
2e380 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2e390 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65  cannot be honore
2e3a0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
2e3b0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
2e3c0 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
2e3d0 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20  otification.)^  
2e3e0 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
2e3f0 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  limit is.** call
2e400 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
2e410 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
2e420 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
2e430 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
2e440 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2e450 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
2e460 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
2e470 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
2e480 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
2e490 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
2e4a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2e4b0 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
2e4c0 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
2e4d0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
2e4e0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2e4f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2e500 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
2e510 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
2e520 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
2e530 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
2e540 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
2e550 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
2e560 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
2e570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2e580 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
2e590 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
2e5a0 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
2e5b0 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
2e5c0 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
2e5d0 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
2e5e0 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
2e5f0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2e600 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2e610 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
2e620 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
2e630 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
2e640 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
2e650 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
2e660 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2e670 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
2e680 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
2e690 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
2e6a0 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
2e6b0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
2e6c0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
2e6d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2e6e0 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
2e6f0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
2e700 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2e710 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
2e720 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
2e730 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
2e740 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
2e750 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
2e760 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
2e770 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2e780 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
2e790 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2e7a0 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
2e7b0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
2e7c0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
2e7d0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
2e7e0 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
2e7f0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
2e800 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
2e810 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
2e820 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
2e830 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
2e840 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
2e850 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
2e860 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
2e870 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2e880 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
2e890 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
2e8a0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
2e8b0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2e8c0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2e8d0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2e8e0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
2e8f0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
2e900 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
2e910 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
2e920 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
2e930 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
2e940 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
2e950 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
2e960 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
2e970 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
2e980 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
2e990 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
2e9a0 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
2e9b0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
2e9c0 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
2e9d0 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
2e9e0 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
2e9f0 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
2ea00 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2ea10 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2ea20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
2ea30 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
2ea40 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
2ea50 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2ea60 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2ea70 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2ea80 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2ea90 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2eaa0 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2eab0 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2eac0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2ead0 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2eae0 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2eaf0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2eb00 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2eb10 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2eb20 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2eb30 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2eb40 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2eb50 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2eb60 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2eb70 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2eb80 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2eb90 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2eba0 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2ebb0 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2ebc0 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2ebd0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2ebe0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2ebf0 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2ec00 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2ec10 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ec20 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
2ec30 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
2ec40 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
2ec50 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
2ec60 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
2ec70 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
2ec80 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
2ec90 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
2eca0 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
2ecb0 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
2ecc0 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
2ecd0 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
2ece0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2ecf0 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
2ed00 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
2ed10 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2ed20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2ed30 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2ed40 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2ed50 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2ed60 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2ed70 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
2ed80 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2ed90 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
2eda0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
2edb0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2edc0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2edd0 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2ede0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2edf0 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
2ee00 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
2ee10 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2ee20 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2ee30 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
2ee40 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2ee50 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2ee60 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
2ee70 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
2ee80 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
2ee90 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
2eea0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2eeb0 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
2eec0 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
2eed0 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
2eee0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
2eef0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
2ef00 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
2ef10 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
2ef20 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
2ef30 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
2ef40 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
2ef50 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
2ef60 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2ef70 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
2ef80 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
2ef90 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
2efa0 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
2efb0 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
2efc0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2efd0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
2efe0 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
2eff0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2f000 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
2f010 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
2f020 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
2f030 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
2f040 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
2f050 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2f060 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2f070 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2f080 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2f090 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2f0a0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2f0b0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
2f0c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f0d0 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
2f0e0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
2f0f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f100 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
2f110 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
2f120 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
2f130 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
2f140 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
2f150 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
2f160 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
2f170 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
2f180 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
2f190 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
2f1a0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
2f1b0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
2f1c0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
2f1d0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
2f1e0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
2f1f0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2f200 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
2f210 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
2f220 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f230 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
2f240 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
2f250 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2f260 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
2f270 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
2f280 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
2f290 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
2f2a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2f2b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2f2c0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
2f2d0 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
2f2e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2f2f0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
2f300 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
2f310 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
2f320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
2f330 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
2f340 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2f350 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
2f360 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2f370 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
2f380 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
2f390 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f3a0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2f3b0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2f3c0 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
2f3d0 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ** SQLite extens
2f3e0 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
2f3f0 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
2f400 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  e zFile..**.** ^
2f410 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
2f420 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50  is zProc..** ^zP
2f430 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e  roc may be 0, in
2f440 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
2f450 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
2f460 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75  y point.** defau
2f470 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
2f480 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
2f490 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f4a0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2f4b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f4c0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  rns.** [SQLITE_O
2f4d0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
2f4e0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2f4f0 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
2f500 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66  es wrong..** ^If
2f510 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2f520 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
2f530 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
2f540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
2f550 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
2f560 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
2f570 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c  ttempt to.** fil
2f580 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
2f590 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2f5a0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
2f5b0 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
2f5c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2f5d0 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61  alloc()]. The ca
2f5e0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
2f5f0 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  * should free th
2f600 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2f610 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2f620 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  ee()]..**.** ^Ex
2f630 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2f640 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
2f650 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2f660 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2f670 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2f680 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2f690 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69   API,.** otherwi
2f6a0 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
2f6b0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   be returned..**
2f6c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
2f6d0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
2f6e0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
2f6f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f700 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2f710 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2f720 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
2f730 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2f740 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
2f750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
2f760 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2f770 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
2f780 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
2f790 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
2f7a0 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
2f7b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
2f7c0 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
2f7d0 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
2f7e0 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
2f7f0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
2f800 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
2f810 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
2f820 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
2f830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f840 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
2f850 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
2f860 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53  Loading.**.** ^S
2f870 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
2f880 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
2f890 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
2f8a0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
2f8b0 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
2f8c0 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
2f8d0 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
2f8e0 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
2f8f0 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
2f900 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
2f910 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
2f920 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
2f930 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
2f940 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
2f950 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
2f960 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2f970 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
2f980 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
2f990 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
2f9a0 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
2f9b0 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
2f9c0 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20  icket #1863..** 
2f9d0 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65  ^Call the sqlite
2f9e0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2f9f0 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
2fa00 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
2fa10 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  ** to turn exten
2fa20 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
2fa30 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
2fa40 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
2fa50 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66  n.** it back off
2fa60 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
2fa70 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2fa80 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
2fa90 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
2faa0 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
2fab0 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
2fac0 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
2fad0 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
2fae0 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69  his API can be i
2faf0 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61  nvoked at progra
2fb00 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64  m startup in ord
2fb10 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  er to register.*
2fb20 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74  * one or more st
2fb30 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
2fb40 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20  extensions that 
2fb50 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c  will be availabl
2fb60 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20  e.** to all new 
2fb70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fb80 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tions]..**.** ^(
2fb90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
2fba0 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
2fbb0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65   the extension e
2fbc0 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e  ntry point.** in
2fbd0 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69   an array that i
2fbe0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2fbf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2fc00 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79  )].  That memory
2fc10 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74  .** is deallocat
2fc20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72  ed by [sqlite3_r
2fc30 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2fc40 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ion()].)^.**.** 
2fc50 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
2fc60 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
2fc70 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
2fc80 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74  t that is.** aut
2fc90 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
2fca0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ed whenever a ne
2fcb0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
2fcc0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70  ection].** is op
2fcd0 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ened using [sqli
2fce0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2fcf0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2fd00 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2fd10 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  open_v2()]..** ^
2fd20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
2fd30 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
2fd40 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
2fd50 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c  s routine.** mul
2fd60 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
2fd70 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
2fd80 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
2fd90 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65  .** ^Automatic e
2fda0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
2fdb0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
2fdc0 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2fdd0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2fde0 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
2fdf0 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
2fe00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2fe10 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
2fe20 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2fe30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
2fe40 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2fe50 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
2fe60 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
2fe70 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
2fe80 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65  s. It undoes the
2fe90 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70   effect of all p
2fea0 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rior.** [sqlite3
2feb0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2fec0 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a  )] calls.)^.**.*
2fed0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
2fee0 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61   disables automa
2fef0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
2ff00 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
2ff10 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2ff20 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2ff30 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
2ff40 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
2ff50 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
2ff60 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
2ff70 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
2ff80 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
2ff90 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
2ffa0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
2ffb0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
2ffc0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
2ffd0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
2ffe0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
2fff0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
30000 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
30010 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
30020 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
30030 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
30040 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
30050 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
30060 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
30070 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
30080 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
30090 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
300a0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
300b0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
300c0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
300d0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
300e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
300f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
30100 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
30110 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30120 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
30130 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
30140 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30150 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
30160 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
30170 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
30180 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
30190 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
301a0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
301b0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
301c0 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
301d0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
301e0 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
301f0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
30200 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
30210 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
30220 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74  called a a "virt
30230 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
30240 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74  ", .** defines t
30250 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
30260 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  n of a [virtual 
30270 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68  tables].  .** Th
30280 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
30290 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20  sists mostly of 
302a0 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
302b0 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41  module..**.** ^A
302c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
302d0 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64  odule is created
302e0 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61   by filling in a
302f0 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69   persistent.** i
30300 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
30310 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61  structure and pa
30320 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20  ssing a pointer 
30330 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65  to that instance
30340 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
30350 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
30360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
30370 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
30380 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74  ..** ^The regist
30390 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
303a0 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
303b0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
303c0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
303d0 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
303e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
303f0 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
30400 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
30410 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
30420 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
30430 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
30440 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
30450 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
30460 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
30470 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
30480 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
30490 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
304a0 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
304b0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
304c0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
304d0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
304e0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
304f0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
30500 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
30510 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
30520 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
30530 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
30540 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30550 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
30560 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
30570 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
30580 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
30590 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
305a0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
305b0 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
305c0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
305d0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
305e0 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
305f0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
30600 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
30610 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
30620 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30630 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
30640 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
30650 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
30660 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
30670 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
30680 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
30690 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
306a0 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
306b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
306c0 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
306d0 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
306e0 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
306f0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
30700 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
30710 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
30720 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
30730 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
30740 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
30750 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30760 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
30770 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
30780 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
30790 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
307a0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
307b0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
307c0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
307d0 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
307e0 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
307f0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
30800 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
30810 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
30820 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
30830 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
30840 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
30850 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
30860 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
30870 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
30880 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
30890 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
308a0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
308b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
308c0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
308d0 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
308e0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
308f0 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
30900 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
30910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30920 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
30930 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
30940 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
30950 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
30960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30970 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
30980 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
30990 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
309a0 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
309b0 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
309c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
309d0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
309e0 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
309f0 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  n.** KEYWORDS: s
30a00 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
30a10 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
30a20 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
30a30 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
30a40 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
30a50 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73  s used to.** pas
30a60 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
30a70 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74  to and receive t
30a80 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68  he reply from th
30a90 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a  e [xBestIndex].*
30aa0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76  * method of a [v
30ab0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30ac0 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64  ule].  The field
30ad0 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
30ae0 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
30af0 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
30b00 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
30b10 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
30b20 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
30b30 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
30b40 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
30b50 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  elds..**.** ^(Th
30b60 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
30b70 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
30b80 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
30b90 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
30ba0 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63  rm:.**.** <pre>c
30bb0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70  olumn OP expr</p
30bc0 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  re>.**.** where 
30bd0 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
30be0 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
30bf0 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70  gt;=.)^  ^(The p
30c00 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74  articular operat
30c10 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20  or is.** stored 
30c20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  in aConstraint[]
30c30 2e 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e  .op.)^  ^(The in
30c40 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
30c50 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
30c60 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
30c70 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43  iColumn.)^  ^(aC
30c80 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
30c90 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
30ca0 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
30cb0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
30cc0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
30cd0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
30ce0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
30cf0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
30d00 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
30d10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70  )^.**.** ^The op
30d20 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
30d30 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
30d40 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
30d50 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
30d60 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
30d70 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
30d80 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
30d90 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
30da0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
30db0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
30dc0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
30dd0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
30de0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
30df0 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74  ..** ^The aConst
30e00 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
30e10 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
30e20 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68   clause terms th
30e30 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61  at are.** releva
30e40 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  nt to the partic
30e50 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
30e60 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
30e70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61  ..**.** ^Informa
30e80 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
30e90 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
30ea0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
30eb0 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68  erBy[]..** ^Each
30ec0 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42   term of aOrderB
30ed0 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75  y records a colu
30ee0 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20  mn of the ORDER 
30ef0 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a  BY clause..**.**
30f00 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   The [xBestIndex
30f10 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  ] method must fi
30f20 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
30f30 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
30f40 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
30f50 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
30f60 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
30f70 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64  er.  ^If argvInd
30f80 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
30f90 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
30fa0 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
30fb0 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
30fc0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
30fd0 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
30fe0 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
30ff0 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
31000 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e   ^(If aConstrain
31010 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
31020 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
31030 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
31040 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
31050 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
31060 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
31070 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
31080 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
31090 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a   SQLite.)^.**.**
310a0 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64   ^The idxNum and
310b0 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
310c0 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
310d0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
310e0 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
310f0 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65  hod..** ^[sqlite
31100 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
31110 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
31120 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
31130 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  ** needToFreeIdx
31140 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
31150 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43  ** ^The orderByC
31160 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
31170 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b  at output from [
31180 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d  xFilter]/[xNext]
31190 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
311a0 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
311b0 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
311c0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
311d0 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
311e0 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
311f0 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
31200 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  ed..**.** ^The e
31210 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c  stimatedCost val
31220 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ue is an estimat
31230 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66  e of the cost of
31240 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61   doing the.** pa
31250 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e  rticular lookup.
31260 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66    A full scan of
31270 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20   a table with N 
31280 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
31290 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66  ave.** a cost of
312a0 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65   N.  A binary se
312b0 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20  arch of a table 
312c0 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  of N entries sho
312d0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f  uld have a.** co
312e0 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74  st of approximat
312f0 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73  ely log(N)..*/.s
31300 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
31310 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20  dex_info {.  /* 
31320 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20  Inputs */.  int 
31330 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
31340 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
31350 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61   of entries in a
31360 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  Constraint */.  
31370 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
31380 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
31390 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
313a0 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
313b0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
313c0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
313d0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
313e0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
313f0 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
31400 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
31410 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
31420 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
31430 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
31440 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
31450 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
31460 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
31470 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
31480 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
31490 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
314a0 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
314b0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20  } *aConstraint; 
314c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61             /* Ta
314d0 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
314e0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
314f0 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42  */.  int nOrderB
31500 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
31510 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
31520 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
31530 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73  BY clause */.  s
31540 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
31550 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20  dex_orderby {.  
31560 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
31570 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31580 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f  Column number */
31590 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
315a0 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20  har desc;       
315b0 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43  /* True for DESC
315c0 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43  .  False for ASC
315d0 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72  . */.  } *aOrder
315e0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
315f0 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
31600 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a  Y clause */.  /*
31610 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
31620 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
31630 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
31640 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
31650 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
31660 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
31670 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
31680 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
31690 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
316a0 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
316b0 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
316c0 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
316d0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
316e0 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
316f0 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
31700 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
31710 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
31720 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
31730 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
31740 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
31750 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
31760 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
31770 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
31780 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
31790 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
317a0 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
317b0 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
317c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
317d0 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
317e0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
317f0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
31800 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
31810 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
31820 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
31830 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
31840 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
31850 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
31860 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
31870 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
31880 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
31890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
318a0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
318b0 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
318c0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
318d0 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
318e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
318f0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
31900 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
31910 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
31920 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
31930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31940 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
31950 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
31960 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
31970 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
31980 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
31990 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
319a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
319b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
319c0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
319d0 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e  le module] name.
319e0 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65  .** ^Module name
319f0 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
31a00 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
31a10 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
31a20 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
31a30 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ing the module a
31a40 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  nd before using 
31a50 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
31a60 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
31a70 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
31a80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75  .**.** ^The modu
31a90 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73  le name is regis
31aa0 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61  tered on the [da
31ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31ac0 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  n] specified.** 
31ad0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
31ae0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61  ameter.  ^The na
31af0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
31b00 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
31b10 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61   .** second para
31b20 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69  meter.  ^The thi
31b30 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
31b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
31b50 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
31b60 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
31b70 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
31b80 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a  .   ^The fourth.
31b90 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
31ba0 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69  an arbitrary cli
31bb0 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ent data pointer
31bc0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
31bd0 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20  through.** into 
31be0 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
31bf0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
31c00 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74  hods of the virt
31c10 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
31c20 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76  .** when a new v
31c30 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
31c40 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  be being created
31c50 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65   or reinitialize
31c60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
31c70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
31c80 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ule_v2() interfa
31c90 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70  ce has a fifth p
31ca0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
31cb0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
31cc0 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
31cd0 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  or the pClientDa
31ce0 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ta.  ^SQLite wil
31cf0 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  l.** invoke the 
31d00 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
31d10 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f  ion (if it is no
31d20 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c  t NULL) when SQL
31d30 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72  ite.** no longer
31d40 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65   needs the pClie
31d50 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  ntData pointer. 
31d60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
31d70 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a  eate_module().**
31d80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
31d90 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69  uivalent to sqli
31da0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
31db0 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
31dc0 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  LL.** destructor
31dd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31de0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
31df0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
31e00 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31e10 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
31e20 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
31e30 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
31e40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
31e50 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
31e60 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
31e70 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
31e80 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
31e90 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
31ea0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
31eb0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
31ec0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
31ed0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
31ee0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
31ef0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31f00 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
31f10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
31f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31f30 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
31f40 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
31f50 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
31f60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
31f70 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
31f80 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
31f90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
31fa0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
31fb0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
31fc0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
31fd0 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
31fe0 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
31ff0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
32000 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
32010 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
32020 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
32030 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
32040 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
32050 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32060 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
32070 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
32080 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
32090 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a  sqlite3_vtab.**.
320a0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
320b0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
320c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
320d0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a  ses a subclass.*
320e0 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  * of this object
320f0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
32100 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
32110 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  ce.** of the [vi
32120 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45  rtual table].  E
32130 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c  ach subclass wil
32140 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64  l.** be tailored
32150 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
32160 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f   needs of the mo
32170 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
32180 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70  ion..** The purp
32190 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
321a0 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
321b0 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
321c0 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63  ds that are.** c
321d0 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64  ommon to all mod
321e0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
321f0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74  ons..**.** ^Virt
32200 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f  ual tables metho
32210 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72  ds can set an er
32220 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61  ror message by a
32230 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74  ssigning a.** st
32240 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
32250 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
32260 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73  ntf()] to zErrMs
32270 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
32280 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
32290 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
322a0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
322b0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
322c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
322d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
322e0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
322f0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
32300 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72  ^After the error
32310 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
32320 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
32330 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
32340 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
32350 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
32360 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
32370 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
32380 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
32390 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
323a0 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
323b0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
323c0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
323d0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
323e0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
323f0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
32400 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
32410 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
32420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32430 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20   NO LONGER USED 
32440 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
32450 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
32460 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
32470 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
32480 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
32490 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
324a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
324b0 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
324c0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
324d0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
324e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
324f0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
32500 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  sor Object.** KE
32510 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
32520 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72  vtab_cursor {vir
32530 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
32540 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  r}.**.** Every [
32550 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
32560 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
32570 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
32580 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  lass of the.** f
32590 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
325a0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  re to describe c
325b0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
325c0 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76  t into the.** [v
325d0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e  irtual table] an
325e0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
325f0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
32600 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
32610 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
32620 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
32630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ** [sqlite3_modu
32640 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e  le.xOpen | xOpen
32650 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
32660 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64  module and are d
32670 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74  estroyed.** by t
32680 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  he [sqlite3_modu
32690 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f  le.xClose | xClo
326a0 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72  se] method.  Cur
326b0 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a  sors are used.**
326c0 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72   by the [xFilter
326d0 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f  ], [xNext], [xEo
326e0 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61  f], [xColumn], a
326f0 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68  nd [xRowid] meth
32700 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f  ods.** of the mo
32710 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75  dule.  Each modu
32720 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32730 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a  n will define.**
32740 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
32750 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75  a cursor structu
32760 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f  re to suit its o
32770 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  wn needs..**.** 
32780 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  This superclass 
32790 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20  exists in order 
327a0 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73  to define fields
327b0 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74   of the cursor t
327c0 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f  hat.** are commo
327d0 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  n to all impleme
327e0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72  ntations..*/.str
327f0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
32800 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69  _cursor {.  sqli
32810 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b  te3_vtab *pVtab;
32820 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c        /* Virtual
32830 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63   table of this c
32840 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69  ursor */.  /* Vi
32850 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
32860 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
32870 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
32880 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
32890 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
328a0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20  PI3REF: Declare 
328b0 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20  The Schema Of A 
328c0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
328d0 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74  .** ^The [xCreat
328e0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
328f0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
32900 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
32910 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
32920 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
32930 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
32940 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
32950 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
32960 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
32970 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
32980 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
32990 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lement..*/.int s
329a0 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
329b0 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
329c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
329d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
329e0 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
329f0 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
32a00 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
32a10 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  ^(Virtual tables
32a20 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
32a30 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
32a40 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
32a50 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
32a60 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
32a70 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
32a80 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
32a90 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
32aa0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
32ab0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
32ac0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
32ad0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
32ae0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a  e overloaded.)^.
32af0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49  **.** ^(This API
32b00 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
32b10 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
32b20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
32b30 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
32b40 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
32b50 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
32b60 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
32b70 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
32b80 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
32b90 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
32ba0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
32bb0 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54  s created.)^  ^T
32bc0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32bd0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
32be0 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
32bf0 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
32c00 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
32c10 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
32c20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
32c30 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
32c40 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
32c50 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
32c60 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
32c70 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  aceholder functi
32c80 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
32c90 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
32ca0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
32cb0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
32cc0 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
32cd0 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
32ce0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
32cf0 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
32d00 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
32d10 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
32d20 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
32d30 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
32d40 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
32d50 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
32d60 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
32d70 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
32d80 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
32d90 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
32da0 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
32db0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
32dc0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
32dd0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
32de0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
32df0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
32e00 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
32e10 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
32e20 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
32e30 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
32e40 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
32e50 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
32e60 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
32e70 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
32e80 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
32e90 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
32ea0 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
32eb0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
32ec0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
32ed0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
32ee0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42   KEYWORDS: {BLOB
32ef0 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68   handle} {BLOB h
32f00 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  andles}.**.** An
32f10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
32f20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
32f30 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42  nts an open BLOB
32f40 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71   on which.** [sq
32f50 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
32f60 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
32f70 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70  OB I/O] can be p
32f80 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62  erformed..** ^Ob
32f90 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
32fa0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
32fb0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
32fc0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64  open()].** and d
32fd0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
32fe0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
32ff0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  )]..** ^The [sql
33000 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
33010 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
33020 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74  lob_write()] int
33030 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62  erfaces.** can b
33040 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f  e used to read o
33050 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75  r write small su
33060 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  bsections of the
33070 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b   BLOB..** ^The [
33080 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
33090 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
330a0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
330b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20   of the BLOB in 
330c0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  bytes..*/.typede
330d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
330e0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c  _blob sqlite3_bl
330f0 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ob;../*.** CAPI3
33100 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42  REF: Open A BLOB
33110 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c   For Incremental
33120 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69   I/O.**.** ^(Thi
33130 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65  s interfaces ope
33140 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ns a [BLOB handl
33150 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74  e | handle] to t
33160 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a  he BLOB located.
33170 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20  ** in row iRow, 
33180 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
33190 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
331a0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a  database zDb;.**
331b0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
331c0 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74   the same BLOB t
331d0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c  hat would be sel
331e0 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
331f0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
33200 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
33210 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
33220 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77  E [rowid] = iRow
33230 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  ;.** </pre>)^.**
33240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67  .** ^If the flag
33250 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
33260 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
33270 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
33280 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64   for read.** and
33290 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e   write access. ^
332a0 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
332b0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
332c0 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73  d for read acces
332d0 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74  s..** ^It is not
332e0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65   possible to ope
332f0 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  n a column that 
33300 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e  is part of an in
33310 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a  dex or primary .
33320 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69  ** key for writi
33330 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e  ng. ^If [foreign
33340 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
33350 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69  ] are enabled, i
33360 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73  t is .** not pos
33370 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
33380 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
33390 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20  art of a [child 
333a0 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67  key] for writing
333b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
333c0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
333d0 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20  name is not the 
333e0 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f  filename that co
333f0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61  ntains.** the da
33400 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65  tabase but rathe
33410 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  r the symbolic n
33420 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
33430 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65  ase that.** appe
33440 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53  ars after the AS
33450 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68   keyword when th
33460 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f  e database is co
33470 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41  nnected using [A
33480 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20  TTACH]..** ^For 
33490 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
334a0 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  e file, the data
334b0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61  base name is "ma
334c0 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d  in"..** ^For TEM
334d0 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61  P tables, the da
334e0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
334f0 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  temp"..**.** ^(O
33500 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
33510 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
33520 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b  ed and the new [
33530 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20  BLOB handle] is 
33540 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
33550 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65  pBlob. Otherwise
33560 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
33570 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
33580 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a   *ppBlob is set.
33590 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20  ** to be a null 
335a0 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54  pointer.)^.** ^T
335b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
335c0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
335d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f  connection] erro
335e0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
335f0 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
33600 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
33610 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
33620 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
33630 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66  and related.** f
33640 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20  unctions. ^Note 
33650 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62  that the *ppBlob
33660 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77   variable is alw
33670 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  ays initialized 
33680 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74  in a.** way that
33690 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74   makes it safe t
336a0 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  o invoke [sqlite
336b0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20  3_blob_close()] 
336c0 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65  on *ppBlob.** re
336d0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
336e0 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
336f0 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  re of this routi
33700 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ne..**.** ^(If t
33710 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c  he row that a BL
33720 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73  OB handle points
33730 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20   to is modified 
33740 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45  by an.** [UPDATE
33750 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20  ], [DELETE], or 
33760 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  by [ON CONFLICT]
33770 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a   side-effects.**
33780 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68   then the BLOB h
33790 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20  andle is marked 
337a0 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a  as "expired"..**
337b0 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66   This is true if
337c0 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   any column of t
337d0 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65  he row is change
337e0 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e  d, even a column
337f0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74  .** other than t
33800 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20  he one the BLOB 
33810 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f  handle is open o
33820 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  n.)^.** ^Calls t
33830 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
33840 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
33850 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
33860 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69  )] for.** a expi
33870 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  red BLOB handle 
33880 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74  fail with an ret
33890 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
338a0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e  ITE_ABORT]..** ^
338b0 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e  (Changes written
338c0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69   into a BLOB pri
338d0 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65  or to the BLOB e
338e0 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a  xpiring are not.
338f0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
33900 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e  y the expiration
33910 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53   of the BLOB.  S
33920 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  uch changes will
33930 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63   eventually.** c
33940 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61  ommit if the tra
33950 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75  nsaction continu
33960 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
33970 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74  .)^.**.** ^Use t
33980 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
33990 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
339a0 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
339b0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
339c0 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
339d0 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61    ^The size of a
339e0 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
339f0 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
33a00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
33a10 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
33a20 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
33a30 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
33a40 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
33a50 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
33a60 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
33a70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33a80 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
33a90 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
33aa0 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
33ab0 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
33ac0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
33ad0 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
33ae0 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
33af0 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
33b00 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
33b10 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
33b20 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
33b30 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
33b40 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
33b50 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
33b60 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
33b70 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
33b80 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
33b90 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
33ba0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
33bb0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a  ob_close()]..*/.
33bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
33bd0 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
33be0 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
33bf0 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
33c00 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
33c10 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
33c20 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
33c30 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
33c40 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
33c50 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
33c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33c70 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
33c80 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  andle.**.** ^Clo
33c90 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  ses an open [BLO
33ca0 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  B handle]..**.**
33cb0 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42   ^Closing a BLOB
33cc0 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
33cd0 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
33ce0 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
33cf0 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
33d00 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
33d10 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
33d20 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
33d30 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
33d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33d50 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
33d60 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e  mode]..** ^If an
33d70 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
33d80 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
33d90 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
33da0 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
33db0 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
33dc0 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
33dd0 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
33de0 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42   ^(Closing the B
33df0 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
33e00 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
33e10 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
33e20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
33e30 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
33e40 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
33e50 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
33e60 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
33e70 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20  is closed.  Any 
33e80 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
33e90 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
33ea0 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
33eb0 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
33ec0 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a  eturn value.)^.*
33ed0 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20  *.** ^(The BLOB 
33ee0 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64  is closed uncond
33ef0 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e  itionally.  Even
33f00 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   if this routine
33f10 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65   returns.** an e
33f20 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42  rror code, the B
33f30 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f  LOB is still clo
33f40 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  sed.)^.**.** ^Ca
33f50 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
33f60 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70  ne with a null p
33f70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20  ointer (such as 
33f80 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  would be returne
33f90 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64  d.** by a failed
33fa0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33fb0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
33fc0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33fd0 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
33fe0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
33ff0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
34000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34010 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
34020 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
34030 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20  .**.** ^Returns 
34040 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
34050 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
34060 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
34070 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c   .** successfull
34080 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68  y opened [BLOB h
34090 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
340a0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  ly argument.  ^T
340b0 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  he.** incrementa
340c0 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69  l blob I/O routi
340d0 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61  nes can only rea
340e0 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67  d or overwriting
340f0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f   existing.** blo
34100 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20  b content; they 
34110 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
34120 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
34130 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34140 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
34150 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
34160 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
34170 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
34180 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
34190 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
341a0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
341b0 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
341c0 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
341d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
341e0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
341f0 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
34200 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
34210 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34220 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34230 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
34240 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
34250 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  vior..*/.int sql
34260 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34270 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
34280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34290 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d  : Read Data From
342a0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
342b0 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tally.**.** ^(Th
342c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
342d0 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
342e0 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42   from an open [B
342f0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  LOB handle] into
34300 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
34310 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
34320 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34330 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
34340 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74  ffer Z.** from t
34350 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74  he open BLOB, st
34360 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
34370 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a   iOffset.)^.**.*
34380 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66  * ^If offset iOf
34390 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
343a0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
343b0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
343c0 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
343d0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
343e0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
343f0 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72   read.  ^If N or
34400 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
34410 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
34420 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
34430 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
34440 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
34450 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74  * ^The size of t
34460 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e  he blob (and hen
34470 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
34480 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
34490 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
344a0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
344b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
344c0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
344d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
344e0 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72  tempt to read fr
344f0 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  om an expired [B
34500 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
34510 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
34520 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
34530 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
34540 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73   ^(On success, s
34550 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
34560 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
34570 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
34580 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
34590 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
345a0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
345b0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
345c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
345d0 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
345e0 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
345f0 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
34600 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
34610 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
34620 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34630 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
34640 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
34650 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
34660 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
34670 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
34680 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
34690 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
346a0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
346b0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
346c0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
346d0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
346e0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
346f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
34700 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  _write()]..*/.in
34710 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
34720 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
34730 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
34740 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
34750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34760 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
34770 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
34780 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  entally.**.** ^T
34790 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
347a0 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
347b0 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
347c0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
347d0 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
347e0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
347f0 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61  ^N bytes of data
34800 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
34810 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
34820 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
34830 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
34840 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
34850 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
34860 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73  BLOB handle] pas
34870 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
34880 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f   argument was no
34890 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20  t opened for.** 
348a0 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61  writing (the fla
348b0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
348c0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
348d0 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c  en()] was zero),
348e0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
348f0 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
34900 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
34910 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
34920 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66  n may only modif
34930 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  y the contents o
34940 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69  f the BLOB; it i
34950 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
34960 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68  e to increase th
34970 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  e size of a BLOB
34980 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e   using this API.
34990 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
349a0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
349b0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
349c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
349d0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
349e0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
349f0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
34a00 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66  is written.  ^If
34a10 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
34a20 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
34a30 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
34a40 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
34a50 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68  s written..** Th
34a60 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
34a70 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  OB (and hence th
34a80 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
34a90 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
34aa0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34ab0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
34ac0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
34ad0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
34ae0 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
34af0 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20   to write to an 
34b00 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
34b10 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
34b20 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
34b30 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
34b40 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f  RT].  ^Writes to
34b50 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f   the BLOB that o
34b60 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72  ccurred.** befor
34b70 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  e the [BLOB hand
34b80 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20  le] expired are 
34b90 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  not rolled back 
34ba0 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61  by the.** expira
34bb0 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64  tion of the hand
34bc0 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  le, though of co
34bd0 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67  urse those chang
34be0 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65  es might.** have
34bf0 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65   been overwritte
34c00 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  n by the stateme
34c10 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20  nt that expired 
34c20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a  the BLOB handle.
34c30 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69  ** or by other i
34c40 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65  ndependent state
34c50 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  ments..**.** ^(O
34c60 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74  n success, sqlit
34c70 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20  e3_blob_write() 
34c80 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
34c90 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
34ca0 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65   an  [error code
34cb0 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
34cc0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
34cd0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34ce0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34cf0 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
34d00 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
34d10 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
34d20 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
34d30 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
34d40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
34d50 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
34d60 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
34d70 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
34d80 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34d90 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
34da0 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
34db0 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
34dc0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
34dd0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
34de0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
34df0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
34e00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
34e10 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
34e20 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ead()]..*/.int s
34e30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
34e40 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
34e50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c  , const void *z,
34e60 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
34e70 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
34e80 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46  I3REF: Virtual F
34e90 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
34ea0 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  ts.**.** A virtu
34eb0 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
34ec0 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
34ed0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
34ee0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
34ef0 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
34f00 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
34f10 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
34f20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
34f30 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
34f40 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
34f50 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
34f60 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
34f70 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
34f80 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
34f90 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
34fa0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
34fb0 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
34fc0 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
34fd0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
34fe0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
34ff0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
35000 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73  ^The sqlite3_vfs
35010 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
35020 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35030 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
35040 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
35050 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20  ^Names are case 
35060 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e  sensitive..** ^N
35070 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65  ames are zero-te
35080 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
35090 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74  trings..** ^If t
350a0 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
350b0 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  , a NULL pointer
350c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
350d0 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73   ^If zVfsName is
350e0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
350f0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
35100 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  turned..**.** ^N
35110 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
35120 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
35130 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
35140 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65  r()..** ^Each ne
35150 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
35160 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
35170 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
35180 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54  ag is set..** ^T
35190 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20  he same VFS can 
351a0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
351b0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
351c0 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20  hout injury..** 
351d0 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73  ^To make an exis
351e0 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
351f0 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
35200 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
35210 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
35220 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
35230 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e   If two differen
35240 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65  t VFSes with the
35250 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  .** same name ar
35260 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68  e registered, th
35270 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
35280 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a  defined.  If a.*
35290 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65  * VFS is registe
352a0 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20  red with a name 
352b0 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20  that is NULL or 
352c0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
352d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
352e0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
352f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67  ed..**.** ^Unreg
35300 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
35310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
35320 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
35330 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66  terface..** ^(If
35340 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
35350 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64   is unregistered
35360 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73  , another VFS is
35370 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68   chosen as.** th
35380 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20  e default.  The 
35390 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e  choice for the n
353a0 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72  ew VFS is arbitr
353b0 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65  ary.)^.*/.sqlite
353c0 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
353d0 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
353e0 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
353f0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
35400 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
35410 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
35420 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
35430 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
35440 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
35450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35460 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Mutexes.**.** Th
35470 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
35480 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
35490 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20  s for thread.** 
354a0 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e  synchronization.
354b0 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65   Though they are
354c0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e   intended for in
354d0 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
354e0 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68   SQLite, code th
354f0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
35500 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65   SQLite is.** pe
35510 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61  rmitted to use a
35520 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
35530 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
35540 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
35550 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74  de contains mult
35560 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
35570 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ions.** of these
35580 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
35590 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
355a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
355b0 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
355c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
355d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e  compile-time.  ^
355e0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  (The following.*
355f0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
35600 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
35610 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
35620 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
35630 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
35640 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
35650 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
35660 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
35670 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
35680 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
35690 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
356a0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
356b0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54   ^The SQLITE_MUT
356c0 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e  EX_NOOP implemen
356d0 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20  tation is a set 
356e0 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74  of routines.** t
356f0 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
35700 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
35710 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
35720 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67  use in.** a sing
35730 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  le-threaded appl
35740 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53  ication.  ^The S
35750 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
35760 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
35770 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
35780 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
35790 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
357a0 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
357b0 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
357c0 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
357d0 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  dows..**.** ^(If
357e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
357f0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
35800 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
35810 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
35820 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
35830 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
35840 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
35850 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
35860 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
35870 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
35880 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49  h the library. I
35890 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a  n this case the.
358a0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  ** application m
358b0 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73  ust supply a cus
358c0 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  tom mutex implem
358d0 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74  entation using t
358e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
358f0 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
35900 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  on of the sqlite
35910 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74  3_config() funct
35920 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61  ion.** before ca
35930 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e  lling sqlite3_in
35940 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e  itialize() or an
35950 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73  y other public s
35960 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74  qlite3_.** funct
35970 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73  ion that calls s
35980 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
35990 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  e().)^.**.** ^Th
359a0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
359b0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
359c0 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
359d0 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
359e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
359f0 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74  o it. ^If it ret
35a00 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61  urns NULL.** tha
35a10 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d  t means that a m
35a20 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62  utex could not b
35a30 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53  e allocated.  ^S
35a40 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
35a50 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
35a60 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
35a70 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  or.  ^(The argum
35a80 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
35a90 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
35aa0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
35ab0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
35ac0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
35ad0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
35ae0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
35af0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
35b00 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
35b10 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
35b20 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
35b30 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35b40 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
35b50 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
35b60 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
35b70 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
35b80 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
35b90 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
35ba0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
35bb0 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  RU.** <li>  SQLI
35bc0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
35bd0 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  LRU2.** </ul>)^.
35be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
35bf0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28   two constants (
35c00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
35c10 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  T and SQLITE_MUT
35c20 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a  EX_RECURSIVE).**
35c30 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
35c40 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
35c50 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
35c60 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77  mutex.  ^The new
35c70 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
35c80 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
35c90 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
35ca0 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
35cb0 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
35cc0 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
35cd0 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
35ce0 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
35cf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
35d00 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
35d10 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
35d20 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
35d30 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
35d40 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
35d50 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
35d60 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
35d70 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69   to.  ^SQLite wi
35d80 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20  ll only request 
35d90 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  a recursive mute
35da0 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68  x in.** cases wh
35db0 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65  ere it really ne
35dc0 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20  eds one.  ^If a 
35dd0 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
35de0 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
35df0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
35e00 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
35e10 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
35e20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
35e30 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
35e40 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
35e50 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
35e60 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
35e70 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74  T..**.** ^The ot
35e80 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61  her allowed para
35e90 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65  meters to sqlite
35ea0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
35eb0 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a  (anything other.
35ec0 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  ** than SQLITE_M
35ed0 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51  UTEX_FAST and SQ
35ee0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
35ef0 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72  SIVE) each retur
35f00 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
35f10 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
35f20 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e  isting mutex.  ^
35f30 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78  Six static mutex
35f40 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62  es are.** used b
35f50 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65  y the current ve
35f60 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e  rsion of SQLite.
35f70 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
35f80 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
35f90 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ay add additiona
35fa0 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  l static mutexes
35fb0 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65  .  Static mutexe
35fc0 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e  s are for intern
35fd0 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
35fe0 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ite only.  Appli
35ff0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
36000 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20   SQLite mutexes 
36010 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e  should.** use on
36020 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  ly the dynamic m
36030 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20  utexes returned 
36040 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  by SQLITE_MUTEX_
36050 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54  FAST or.** SQLIT
36060 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36070 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  E..**.** ^Note t
36080 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
36090 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
360a0 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
360b0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
360c0 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
360d0 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
360e0 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
360f0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
36100 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
36110 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
36120 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74  very call.  ^But
36130 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a   for the static.
36140 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
36150 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
36160 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
36170 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
36180 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
36190 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
361a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
361b0 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
361c0 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
361d0 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
361e0 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
361f0 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65   mutex.  ^SQLite
36200 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
36210 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
36220 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
36230 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
36240 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
36250 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
36260 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77  t be in.** use w
36270 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
36280 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d  llocated.  Attem
36290 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
362a0 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
362b0 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
362c0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
362d0 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65  ior.  ^SQLite ne
362e0 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
362f0 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
36300 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  x..**.** ^The sq
36310 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
36320 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
36330 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
36340 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
36350 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
36360 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74  .  ^If another t
36370 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
36380 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65   within the mute
36390 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  x,.** sqlite3_mu
363a0 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c  tex_enter() will
363b0 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74   block and sqlit
363c0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77  e3_mutex_try() w
363d0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  ill return.** SQ
363e0 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65  LITE_BUSY.  ^The
363f0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
36400 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
36410 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
36420 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  K].** upon succe
36430 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28  ssful entry.  ^(
36440 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20  Mutexes created 
36450 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
36460 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
36470 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d  can be entered m
36480 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79  ultiple times by
36490 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
364a0 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73  ..** In such cas
364b0 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
364c0 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
364d0 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
364e0 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
364f0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
36500 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20  * can enter.)^  
36510 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68  ^(If the same th
36520 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e  read tries to en
36530 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  ter any other.**
36540 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d   kind of mutex m
36550 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74  ore than once, t
36560 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
36570 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c  ndefined..** SQL
36580 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
36590 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
365a0 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
365b0 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
365c0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d  s.)^.**.** ^(Som
365d0 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
365e0 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
365f0 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
36600 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
36610 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
36620 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
36630 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
36640 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
36650 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
36660 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
36670 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
36680 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
36690 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65  re only ever use
366a0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  s.** sqlite3_mut
366b0 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f  ex_try() as an o
366c0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74  ptimization so t
366d0 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c  his is acceptabl
366e0 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a  e behavior.)^.**
366f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36700 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72  _mutex_leave() r
36710 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d  outine exits a m
36720 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a  utex that was.**
36730 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65   previously ente
36740 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20  red by the same 
36750 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20  thread.   ^(The 
36760 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
36770 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
36780 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
36790 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
367a0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
367b0 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
367c0 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
367d0 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77  cated.  SQLite w
367e0 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20  ill.** never do 
367f0 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  either.)^.**.** 
36800 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
36810 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
36820 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
36830 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
36840 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
36850 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
36860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36870 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
36880 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
36890 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
368a0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
368b0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
368c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
368d0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
368e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
368f0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
36900 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
36910 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
36920 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
36930 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
36940 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
36950 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36960 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
36970 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
36980 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
36990 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
369a0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
369b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
369c0 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
369d0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
369e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
369f0 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69  s structure defi
36a00 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65  nes the low-leve
36a10 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  l routines.** us
36a20 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  ed to allocate a
36a30 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a  nd use mutexes..
36a40 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74  **.** Usually, t
36a50 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
36a60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36a70 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c   provided by SQL
36a80 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69  ite are.** suffi
36a90 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74  cient, however t
36aa0 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20  he user has the 
36ab0 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69  option of substi
36ac0 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a  tuting a custom.
36ad0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
36ae0 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65  n for specialize
36af0 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72  d deployments or
36b00 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69   systems for whi
36b10 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65  ch SQLite.** doe
36b20 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  s not provide a 
36b30 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
36b40 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  ntation. In this
36b50 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a   case, the user.
36b60 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70  ** creates and p
36b70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74  opulates an inst
36b80 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
36b90 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a  ucture to pass.*
36ba0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  * to sqlite3_con
36bb0 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68  fig() along with
36bc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
36bd0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
36be0 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  n..** Additional
36bf0 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ly, an instance 
36c00 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
36c10 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  e can be used as
36c20 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61   an.** output va
36c30 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72  riable when quer
36c40 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20  ying the system 
36c50 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
36c60 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
36c70 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74  ntation, using t
36c80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
36c90 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69  G_GETMUTEX] opti
36ca0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  on..**.** ^The x
36cb0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
36cc0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
36cd0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e   structure is in
36ce0 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  voked as.** part
36cf0 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69   of system initi
36d00 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65  alization by the
36d10 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
36d20 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a  ize() function..
36d30 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e  ** ^The xMutexIn
36d40 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  it routine is ca
36d50 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78  lle by SQLite ex
36d60 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65  actly once for e
36d70 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65  ach.** effective
36d80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36d90 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e  3_initialize()].
36da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
36db0 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66  exEnd method def
36dc0 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
36dd0 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
36de0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
36df0 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20  system shutdown 
36e00 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
36e10 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69  hutdown() functi
36e20 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65  on. The.** imple
36e30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
36e40 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65  s method is expe
36e50 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  cted to release 
36e60 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a  all outstanding.
36e70 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74  ** resources obt
36e80 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74  ained by the mut
36e90 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65  ex methods imple
36ea0 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63  mentation, espec
36eb0 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f  ially.** those o
36ec0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78  btained by the x
36ed0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
36ee0 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e  .  ^The xMutexEn
36ef0 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
36f00 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   is invoked exac
36f10 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  tly once for eac
36f20 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
36f30 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
36f40 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61  **.** ^(The rema
36f50 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68  ining seven meth
36f60 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74  ods defined by t
36f70 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78  his structure (x
36f80 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78  MutexAlloc,.** x
36f90 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65  MutexFree, xMute
36fa0 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72  xEnter, xMutexTr
36fb0 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20  y, xMutexLeave, 
36fc0 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a  xMutexHeld and.*
36fd0 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  * xMutexNotheld)
36fe0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66   implement the f
36ff0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
37000 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c  ces (respectivel
37010 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y):.**.** <ul>.*
37020 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37030 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
37040 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
37050 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
37060 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a  x_free()] </li>.
37070 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
37080 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
37090 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
370a0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
370b0 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a  ex_try()] </li>.
370c0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
370d0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
370e0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
370f0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37100 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  ex_held()] </li>
37110 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
37120 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37130 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  ld()] </li>.** <
37140 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
37150 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
37160 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62   is that the pub
37170 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20  lic sqlite3_XXX 
37180 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72  functions enumer
37190 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69  ated.** above si
371a0 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e  lently ignore an
371b0 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68  y invocations th
371c0 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70  at pass a NULL p
371d0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a  ointer instead.*
371e0 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  * of a valid mut
371f0 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69  ex handle. The i
37200 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37210 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65  f the methods de
37220 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  fined.** by this
37230 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e   structure are n
37240 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68  ot required to h
37250 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c  andle this case,
37260 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20   the results.** 
37270 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c  of passing a NUL
37280 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
37290 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  d of a valid mut
372a0 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e  ex handle are un
372b0 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e  defined.** (i.e.
372c0 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c   it is acceptabl
372d0 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20  e to provide an 
372e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
372f0 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66  hat segfaults if
37300 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64  .** it is passed
37310 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29   a NULL pointer)
37320 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
37330 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20  exInit() method 
37340 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
37350 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65  fe.  ^It must be
37360 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20   harmless to.** 
37370 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69  invoke xMutexIni
37380 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65  t() mutiple time
37390 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
373a0 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69  e process and wi
373b0 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65  thout.** interve
373c0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d  ning calls to xM
373d0 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f  utexEnd().  Seco
373e0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
373f0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d  t calls to.** xM
37400 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20  utexInit() must 
37410 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
37420 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d   ^xMutexInit() m
37430 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
37440 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te memory alloca
37450 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d  tion ([sqlite3_m
37460 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20  alloc()].** and 
37470 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e  its associates).
37480 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d    ^Similarly, xM
37490 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74  utexAlloc() must
374a0 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
374b0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
374c0 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69  tion for a stati
374d0 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76  c mutex.  ^Howev
374e0 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  er xMutexAlloc()
374f0 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a   may use SQLite.
37500 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
37510 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20  tion for a fast 
37520 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  or recursive mut
37530 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ex..**.** ^SQLit
37540 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
37550 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65  e xMutexEnd() me
37560 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  thod when [sqlit
37570 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69  e3_shutdown()] i
37580 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74  s.** called, but
37590 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69   only if the pri
375a0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65  or call to xMute
375b0 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53  xInit returned S
375c0 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20  QLITE_OK..** If 
375d0 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73  xMutexInit fails
375e0 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20   in any way, it 
375f0 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63  is expected to c
37600 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74  lean up after it
37610 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  self.** prior to
37620 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74   returning..*/.t
37630 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37640 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
37650 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ods sqlite3_mute
37660 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  x_methods;.struc
37670 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
37680 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
37690 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f  (*xMutexInit)(vo
376a0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  id);.  int (*xMu
376b0 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20  texEnd)(void);. 
376c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a   sqlite3_mutex *
376d0 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69  (*xMutexAlloc)(i
376e0 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d  nt);.  void (*xM
376f0 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65  utexFree)(sqlite
37700 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
37710 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72  id (*xMutexEnter
37720 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37730 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37740 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d  exTry)(sqlite3_m
37750 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
37760 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73  (*xMutexLeave)(s
37770 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37780 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48  .  int (*xMutexH
37790 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  eld)(sqlite3_mut
377a0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
377b0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71  MutexNotheld)(sq
377c0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
377d0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
377e0 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69  EF: Mutex Verifi
377f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
37800 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
37810 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
37820 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
37830 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
37840 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
37850 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
37860 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
37870 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51  ements.  ^The SQ
37880 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
37890 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
378a0 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
378b0 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
378c0 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
378d0 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
378e0 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
378f0 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
37900 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f    ^The SQLite co
37910 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
37920 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
37930 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
37940 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
37950 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
37960 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
37970 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65  BUG flag.  ^Exte
37980 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65  rnal mutex imple
37990 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
379a0 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20  e only required 
379b0 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65  to provide these
379c0 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c   routines if SQL
379d0 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20  ITE_DEBUG is.** 
379e0 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e  defined and if N
379f0 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66  DEBUG is not def
37a00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
37a10 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
37a20 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
37a30 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
37a40 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
37a50 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
37a60 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
37a70 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
37a80 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
37a90 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
37aa0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75  tion is not requ
37ab0 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64  ired to provided
37ac0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
37ad0 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
37ae0 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72  hat actually wor
37af0 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d  k. If the implem
37b00 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
37b10 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e  t provide workin
37b20 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  g.** versions of
37b30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
37b40 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65   it should at le
37b50 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62  ast provide stub
37b60 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a  s that always.**
37b70 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20   return true so 
37b80 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f  that one does no
37b90 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61  t get spurious a
37ba0 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65  ssertion failure
37bb0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
37bc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
37bd0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
37be0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
37bf0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
37c00 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
37c10 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20  eturn 1.   This 
37c20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e  seems counter-in
37c30 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a  tuitive since.**
37c40 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74   clearly the mut
37c50 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c  ex cannot be hel
37c60 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
37c70 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65   exist.  But the
37c80 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74  .** the reason t
37c90 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f  he mutex does no
37ca0 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75  t exist is becau
37cb0 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20  se the build is 
37cc0 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74  not.** using mut
37cd0 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f  exes.  And we do
37ce0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73   not want the as
37cf0 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e  sert() containin
37d00 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f  g the.** call to
37d10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
37d20 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73  eld() to fail, s
37d30 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  o a non-zero ret
37d40 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70  urn is.** the ap
37d50 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20  propriate thing 
37d60 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c  to do.  ^The sql
37d70 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37d80 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ld().** interfac
37d90 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65  e should also re
37da0 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65  turn 1 when give
37db0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
37dc0 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45  ..*/.#ifndef NDE
37dd0 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  BUG.int sqlite3_
37de0 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
37df0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
37e00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
37e10 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
37e20 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  tex*);.#endif../
37e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
37e40 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a  utex Types.**.**
37e50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   The [sqlite3_mu
37e60 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74  tex_alloc()] int
37e70 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73  erface takes a s
37e80 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
37e90 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f  * which is one o
37ea0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
37eb0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
37ec0 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74   The set of stat
37ed0 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63  ic mutexes may c
37ee0 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53  hange from one S
37ef0 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f  QLite release to
37f00 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
37f10 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
37f20 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75   override the bu
37f30 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67  ilt-in mutex log
37f40 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72  ic must be.** pr
37f50 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d  epared to accomm
37f60 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c  odate additional
37f70 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
37f80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
37f90 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20  TE_MUTEX_FAST   
37fa0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
37fb0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37fc0 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
37fd0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
37fe0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37ff0 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66  MASTER    2.#def
38000 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
38010 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20  _STATIC_MEM     
38020 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    3  /* sqlite3_
38030 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66  malloc() */.#def
38040 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
38050 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20  _STATIC_MEM2    
38060 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44    4  /* NOT USED
38070 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38080 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
38090 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20  OPEN      4  /* 
380a0 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e  sqlite3BtreeOpen
380b0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
380c0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
380d0 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f  C_PRNG      5  /
380e0 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  * sqlite3_random
380f0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
38100 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
38110 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f  C_LRU       6  /
38120 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20  * lru page list 
38130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38140 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
38150 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c  RU2      7  /* l
38160 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a  ru page list */.
38170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38180 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75   Retrieve the mu
38190 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61  tex for a databa
381a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
381b0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
381c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
381d0 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74  inter the [sqlit
381e0 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
381f0 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c   that .** serial
38200 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74  izes access to t
38210 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38220 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69  nection] given i
38230 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  n the argument.*
38240 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65  * when the [thre
38250 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53  ading mode] is S
38260 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49  erialized..** ^I
38270 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  f the [threading
38280 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65   mode] is Single
38290 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69  -thread or Multi
382a0 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69  -thread then thi
382b0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  s.** routine ret
382c0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
382d0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
382e0 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64  mutex *sqlite3_d
382f0 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a  b_mutex(sqlite3*
38300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38310 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f  EF: Low-Level Co
38320 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73  ntrol Of Databas
38330 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  e Files.**.** ^T
38340 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
38350 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
38360 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69  rface makes a di
38370 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  rect call to the
38380 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
38390 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20   method for the 
383a0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
383b0 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ods] object asso
383c0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61  ciated.** with a
383d0 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
383e0 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20  base identified 
383f0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  by the second ar
38400 67 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20  gument. ^The.** 
38410 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
38420 62 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20  base "main" for 
38430 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
38440 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20  e or "temp" for 
38450 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61  the.** TEMP data
38460 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d  base, or the nam
38470 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61  e that appears a
38480 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77  fter the AS keyw
38490 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ord for.** datab
384a0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64  ases that are ad
384b0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41  ded using the [A
384c0 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61  TTACH] SQL comma
384d0 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70  nd..** ^A NULL p
384e0 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73  ointer can be us
384f0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22  ed in place of "
38500 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74  main" to refer t
38510 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61  o the.** main da
38520 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20  tabase file..** 
38530 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
38540 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
38550 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
38560 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64  .** are passed d
38570 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20  irectly through 
38580 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  to the second an
38590 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  d third paramete
385a0 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69  rs of.** the xFi
385b0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
385c0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  .  ^The return v
385d0 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c  alue of the xFil
385e0 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68  eControl.** meth
385f0 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72  od becomes the r
38600 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
38610 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a  his routine..**.
38620 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
38630 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62  d parameter (zDb
38640 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d  Name) does not m
38650 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66  atch the name of
38660 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74   any.** open dat
38670 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e  abase file, then
38680 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73   SQLITE_ERROR is
38690 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69   returned.  ^Thi
386a0 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
386b0 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
386c0 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
386d0 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
386e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
386f0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
38700 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65  _errmsg()].  The
38710 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c   underlying xFil
38720 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
38730 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65  might.** also re
38740 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  turn SQLITE_ERRO
38750 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20  R.  There is no 
38760 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69  way to distingui
38770 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e  sh between.** an
38780 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61   incorrect zDbNa
38790 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45  me and an SQLITE
387a0 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72  _ERROR return fr
387b0 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  om the underlyin
387c0 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  g.** xFileContro
387d0 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20  l method..**.** 
387e0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
387f0 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
38800 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  E].*/.int sqlite
38810 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73  3_file_control(s
38820 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
38830 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e  har *zDbName, in
38840 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t op, void*);../
38850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
38860 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
38870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38880 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c  te3_test_control
38890 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
388a0 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74  used to read out
388b0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61   internal.** sta
388c0 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64  te of SQLite and
388d0 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74   to inject fault
388e0 73 20 69 6e