/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact fef9e187420e234ecc45962f76dfb30065c3ba34:


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 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
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: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully 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 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8580: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8590: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
85a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
85b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
85c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
85d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
85e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
85f0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8600: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8610: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8620: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8630: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8640: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8650: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8660: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8670: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8680: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8690: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
86a0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
86b0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
86c0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
86d0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
86e0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
86f0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8700: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8710: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8720: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8730: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8740: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8760: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8770: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8780: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8790: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
87a0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
87b0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
87c0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
87d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
87e0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
87f0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8800: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8810: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8820: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8830: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8840: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8850: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8860: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8870: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8880: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8890: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
88a0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
88b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
88c0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
88d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
88e0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
88f0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
8900: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
8910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8920: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
8930: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
8940: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
8950: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
8960: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
8970: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
8980: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
89a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
89b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
89c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
89d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
89e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
89f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
8a00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8a10: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8a20: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8a30: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
8a40: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
8a50: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
8a60: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8a70: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a80: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
8a90: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
8aa0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
8ab0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
8ac0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
8ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8ae0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8b00: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8b10: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8b20: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
8b30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8b40: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
8b50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8b60: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8b70: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8b80: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
8b90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ba0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8bb0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8bc0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
8bd0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
8be0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8bf0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8c00: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8c10: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8c20: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8c30: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8c40: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
8c50: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
8c60: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
8c70: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
8c80: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
8c90: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
8ca0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8cb0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8cc0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8cd0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8ce0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8cf0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8d00: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8d10: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8d20: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8d40: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
8d50: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
8d60: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
8d90: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
8da0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8db0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8dc0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8dd0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8de0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8df0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8e00: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8e10: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8e20: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8e30: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8e40: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8e60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8e80: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
8e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8ea0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8eb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8ec0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8ed0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8ee0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8ef0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
8f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8f10: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
8f20: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
8f30: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
8f40: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
8f50: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
8f60: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
8f70: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
8f80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8f90: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8fa0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
8fb0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
8fc0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
8fd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
8fe0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
8ff0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9000: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9010: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9020: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9030: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9040: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9050: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9060: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9070: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9080: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9090: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
90a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
90b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
90c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
90d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
90e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
90f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9100: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9110: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9120: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9130: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9140: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9150: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9160: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9170: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9180: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9190: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
91a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
91b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
91c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
91d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
91e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
91f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9200: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9210: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9220: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9230: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9240: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9250: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9260: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9280: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9290: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
92a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
92b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
92c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
92d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
92e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
92f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9300: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9310: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9320: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9330: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9340: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9350: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9360: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9370: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9380: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9390: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
93a0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
93b0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
93c0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
93d0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
93e0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
93f0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9400: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9410: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9420: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9430: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9440: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9450: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9460: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9470: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9480: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9490: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
94a0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
94b0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
94c0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
94d0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
94e0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
94f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9500: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9510: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9520: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9530: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9540: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9550: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9560: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9570: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9580: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9590: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
95a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
95b0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
95c0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
95d0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
95e0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
95f0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9600: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9610: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9620: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9630: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9640: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9650: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9660: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9680: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9690: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
96a0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
96b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
96c0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
96d0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
96e0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
96f0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9700: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9710: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9720: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9730: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9740: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9750: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9760: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9770: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9780: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9790: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
97a0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
97b0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
97c0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
97d0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
97e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
97f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9800: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9810: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9820: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9830: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9840: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9850: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9860: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9870: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9880: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9890: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
98a0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
98b0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
98c0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
98d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
98e0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
98f0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
9900: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
9910: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
9920: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
9930: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
9940: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
9950: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
9960: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
9970: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
9980: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
9990: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
99a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
99b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
99c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
99d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
99e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
99f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
9a00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
9a10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
9a20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
9a30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
9a40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9a50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
9a60: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
9a70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9a80: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9aa0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9ab0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9ac0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9ad0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
9ae0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
9af0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
9b00: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
9b10: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
9b20: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9b30: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9b40: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9b50: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9b60: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9b70: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9b80: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9b90: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9bb0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9bc0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
9bd0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
9be0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
9bf0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
9c00: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
9c10: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
9c20: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9c30: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9c40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9c50: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9c60: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9c70: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9c80: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9c90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9ca0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9cb0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9cc0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
9cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
9ce0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9cf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9d00: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
9d10: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
9d20: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9d30: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9d40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9d50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9d60: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9d70: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9d80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9d90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9da0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9db0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9dc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9dd0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
9de0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
9df0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
9e00: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
9e10: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
9e20: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9e30: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9e40: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9e50: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9e60: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9e70: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9e80: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9e90: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9ea0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9eb0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9ec0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9ed0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9ee0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
9ef0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
9f00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9f10: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
9f20: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9f30: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9f40: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9f50: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9f60: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9f70: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9f80: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9f90: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9fa0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9fb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9fc0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
9fd0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
9fe0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9ff0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a000: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a010: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a020: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a030: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a040: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a050: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a060: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a070: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a080: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a090: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a0a0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a0b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a0c0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a0d0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a0e0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a0f0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a100: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a110: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a120: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a130: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a140: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a150: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a160: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a170: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a180: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a190: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a1a0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a1b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a1c0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a1d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a1e0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a1f0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a200: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a210: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a220: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a230: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a240: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a250: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a260: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a270: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
a280: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
a290: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
a2a0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
a2b0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
a2c0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
a2d0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
a2e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a2f0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
a300: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
a310: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
a320: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
a330: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
a340: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
a350: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
a360: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
a370: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
a380: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
a390: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
a3a0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a3b0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
a3c0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
a3d0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
a3e0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
a3f0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
a400: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
a410: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
a420: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
a430: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
a440: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a450: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
a460: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
a470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a480: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
a490: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
a4a0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
a4b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a4c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
a4d0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
a4e0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
a4f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
a500: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
a510: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
a520: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
a530: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
a540: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
a550: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
a560: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
a570: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
a580: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a590: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
a5a0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
a5b0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
a5c0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
a5d0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
a5e0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
a5f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
a610: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
a620: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
a630: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
a640: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a650: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
a660: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
a670: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a680: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a690: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a6b0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
a6c0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
a6d0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
a6e0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
a6f0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
a700: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
a710: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
a720: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
a730: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
a740: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
a750: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
a760: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
a770: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
a780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
a790: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
a7a0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
a7b0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
a7c0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
a7d0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
a7f0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
a800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
a810: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
a820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
a830: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
a840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a850: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
a860: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
a870: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
a880: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
a890: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
a8a0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
a8b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
a8c0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
a8d0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
a8e0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
a8f0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
a900: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
a910: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
a920: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
a930: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
a940: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
a950: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
a960: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
a970: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
a980: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
a990: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
a9a0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
a9b0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
a9c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a9d0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a9e0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
a9f0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
aa00: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
aa10: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
aa20: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
aa30: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
aa40: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
aa50: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
aa60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
aa70: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
aa80: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
aa90: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
aaa0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
aab0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
aac0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
aad0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
aae0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
aaf0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ab00: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ab10: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ab20: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ab30: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ab40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ab50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
ab60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ab70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
ab80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ab90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aba0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
abb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
abc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
abd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
abe0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
abf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ac00: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ac10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ac20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ac30: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ac40: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
ac50: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
ac60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ac70: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
ac80: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
ac90: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
aca0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
acb0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
acc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
acd0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ace0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
acf0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ad00: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ad10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ad20: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ad30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ad40: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
ad50: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
ad60: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ad70: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
ad80: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
ad90: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
ada0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
adb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
adc0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
add0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ade0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
adf0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ae00: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ae10: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ae20: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ae30: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ae40: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ae50: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ae60: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ae70: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ae80: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ae90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
aea0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
aeb0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
aec0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
aed0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
aee0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
aef0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
af00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
af10: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
af20: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
af30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
af40: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
af50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
af60: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
af70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
af80: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
af90: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
afa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afc0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
afd0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
afe0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
aff0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b000: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b010: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b020: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b030: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b040: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b050: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b060: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b070: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b080: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b090: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b0a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b0b0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b0c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b0d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b0e0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b0f0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b100: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b110: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b120: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b130: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b140: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b150: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b160: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b170: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b190: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b1b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b1c0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b1d0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b1e0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b1f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b200: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b210: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b220: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b230: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b240: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b250: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b260: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b270: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
b280: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
b290: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
b2a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b2b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
b2c0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
b2d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b2e0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
b2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b300: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
b310: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
b320: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
b330: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
b340: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
b350: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
b360: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
b370: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
b380: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
b390: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
b3a0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
b3b0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
b3c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3d0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
b3e0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
b3f0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
b400: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
b410: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
b420: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
b430: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b440: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
b450: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
b460: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
b470: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
b480: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
b490: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
b4a0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
b4b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
b4c0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
b4d0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
b4e0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
b4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
b500: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
b510: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
b520: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
b530: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
b540: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
b550: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
b560: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
b570: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
b580: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
b590: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
b5a0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
b5b0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
b5c0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
b5d0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
b5e0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
b5f0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
b600: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
b610: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
b620: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
b630: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
b640: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
b650: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
b660: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b670: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
b680: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
b690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
b6a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
b6b0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
b6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b6d0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
b6e0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
b6f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
b700: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b710: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b720: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
b730: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
b740: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
b750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b760: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
b770: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
b780: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
b790: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
b7a0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
b7b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
b7c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
b7d0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
b7e0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
b7f0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
b800: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
b810: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
b820: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
b830: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
b840: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
b850: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
b860: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
b870: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
b880: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
b890: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
b8a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b8b0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
b8c0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
b8d0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
b8e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
b8f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
b900: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
b910: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
b920: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b930: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
b940: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
b950: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
b960: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
b970: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
b980: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
b990: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
b9a0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
b9b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
b9c0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
b9d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
b9e0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
b9f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
ba00: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ba10: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
ba20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ba30: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
ba40: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
ba50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ba60: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ba70: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ba80: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
ba90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
baa0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
bab0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
bac0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
bad0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
bae0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
baf0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
bb00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
bb10: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
bb20: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
bb30: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
bb40: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
bb50: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
bb60: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
bb70: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
bb80: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
bb90: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
bba0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
bbb0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bbc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bbd0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
bbe0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbf0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
bc00: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
bc10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
bc20: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
bc30: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
bc40: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
bc50: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
bc60: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
bc70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bc80: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
bc90: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
bca0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
bcb0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
bcc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
bcd0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
bce0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
bcf0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bd00: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
bd10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
bd20: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
bd30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bd40: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
bd50: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
bd60: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
bd70: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
bd80: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
bd90: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
bda0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
bdb0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
bdc0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
bdd0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
bde0: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
bdf0: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
be00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
be10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
be20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
be30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
be40: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
be50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
be60: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
be70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
be80: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
be90: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
bea0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
beb0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
bec0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
bed0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
bee0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
bef0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bf00: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
bf10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bf20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
bf30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
bf40: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
bf50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bf60: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
bf70: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
bf80: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
bf90: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
bfa0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
bfb0: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
bfc0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
bfd0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
bfe0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
bff0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
c000: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
c010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
c020: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
c030: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c040: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
c050: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
c060: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
c070: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c090: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
c0a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
c0b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c0c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
c0d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
c0e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c0f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
c100: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
c110: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
c120: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
c130: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
c140: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
c150: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
c160: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
c170: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
c180: 72 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c  rface should onl
c190: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c1a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c1b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c1c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c1d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c1e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c1f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c200: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c210: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c220: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c230: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c240: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c250: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c260: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c270: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c280: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c290: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c2a0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c2c0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c2d0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c2e0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c2f0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c300: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c310: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c320: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c330: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c340: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c350: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c360: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c370: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c380: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
c390: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
c3a0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
c3b0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
c3c0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
c3d0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
c3e0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
c3f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
c400: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
c410: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
c420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c430: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
c440: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
c450: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c460: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c470: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c480: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
c490: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
c4a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4b0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
c4c0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
c4d0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
c4e0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
c4f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c500: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
c510: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
c520: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
c530: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
c540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c550: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
c560: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c570: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
c580: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c590: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
c5a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
c5b0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
c5c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
c5d0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
c5e0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
c5f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
c600: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
c610: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
c620: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
c630: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c640: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
c650: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
c660: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c670: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
c680: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
c690: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
c6a0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
c6b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
c6c0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
c6d0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
c6e0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
c6f0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
c700: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
c710: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
c720: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
c730: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
c740: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
c750: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
c760: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
c770: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
c780: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
c790: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
c7a0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
c7b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
c7c0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
c7d0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
c7e0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c7f0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
c800: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
c810: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
c820: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
c830: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
c840: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
c850: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
c860: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
c870: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
c880: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
c890: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
c8a0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
c8b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
c8c0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
c8d0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
c8e0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
c8f0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
c900: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
c910: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
c920: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
c930: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
c940: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
c950: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
c960: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
c970: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
c980: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
c990: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c9a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
c9b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
c9c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
c9d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
c9e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
c9f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
ca00: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
ca10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ca20: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
ca30: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
ca40: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
ca50: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
ca60: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
ca70: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
ca80: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
ca90: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
caa0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
cab0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
cac0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
cad0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
cae0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
caf0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
cb00: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
cb10: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
cb20: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
cb30: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
cb40: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
cb50: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
cb60: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
cb70: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
cb80: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
cb90: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
cba0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
cbb0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
cbc0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
cbd0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
cbe0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
cbf0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
cc00: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
cc10: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
cc20: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
cc30: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
cc40: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cc50: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
cc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
cc70: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
cc80: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
cc90: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
cca0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
ccb0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
ccc0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
ccd0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
cce0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
ccf0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
cd00: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
cd10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
cd20: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
cd30: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
cd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
cd50: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
cd60: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
cd70: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
cd80: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
cd90: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
cda0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
cdb0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
cdc0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
cdd0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
cde0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
cdf0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
ce00: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ce10: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
ce20: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ce30: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
ce40: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
ce50: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
ce60: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
ce70: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
ce80: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
ce90: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cea0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
ceb0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cec0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
ced0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cee0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cef0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cf00: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cf10: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cf20: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cf30: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
cf40: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
cf50: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
cf60: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
cf70: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
cf80: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
cf90: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
cfa0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
cfb0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
cfc0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
cfd0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
cfe0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
cff0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
d000: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d010: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
d020: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
d030: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
d040: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
d050: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
d060: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
d070: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
d080: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
d090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d0a0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
d0b0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
d0c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
d0d0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
d0e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d0f0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
d100: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
d110: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
d120: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
d130: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
d140: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
d150: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
d160: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d170: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
d180: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
d190: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
d1a0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
d1b0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
d1c0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
d1d0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
d1e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
d1f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
d200: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
d210: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
d220: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
d230: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
d240: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
d250: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d260: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d270: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
d280: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
d290: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d2a0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
d2b0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
d2c0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
d2d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d2e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
d2f0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
d300: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
d310: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
d320: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
d330: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
d340: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
d350: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
d360: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
d370: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
d380: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
d390: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
d3a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
d3b0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
d3c0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
d3d0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
d3e0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
d3f0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
d400: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
d410: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
d420: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
d430: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d440: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
d450: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
d460: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
d470: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d480: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d490: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
d4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
d4b0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
d4c0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
d4d0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
d4e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d4f0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
d500: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
d510: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
d520: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
d530: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
d540: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
d550: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
d560: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
d570: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
d580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
d590: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d5a0: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
d5b0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
d5c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d5d0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
d5e0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
d5f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d600: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
d610: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
d620: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
d630: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
d640: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
d650: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d660: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
d670: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
d680: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
d690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d6a0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d6b0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d6c0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d6d0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d6e0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d6f0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d700: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d710: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
d720: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
d730: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d740: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d750: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d760: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d770: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
d780: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d790: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
d7a0: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
d7b0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
d7c0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
d7d0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d7e0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d7f0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d800: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d810: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d820: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d830: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d840: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d850: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d860: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d870: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d880: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d890: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d8a0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d8b0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
d8c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
d8d0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
d8e0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
d8f0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
d900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d910: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
d920: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d930: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d940: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
d950: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
d960: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d970: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d980: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d990: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d9a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d9b0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d9c0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d9d0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
d9e0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
d9f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
da00: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
da10: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
da20: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
da30: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
da40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
da50: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
da60: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
da70: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
da80: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
da90: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
daa0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
dab0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
dac0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dad0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
dae0: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
daf0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
db00: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
db10: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
db20: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
db30: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
db40: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
db50: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
db60: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
db70: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
db80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
db90: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
dba0: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
dbb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dbc0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dbd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dbe0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dbf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc10: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc20: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
dc30: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
dc40: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
dc50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
dc60: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
dc70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
dc80: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
dc90: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
dca0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
dcb0: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
dcc0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
dcd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dce0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
dcf0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
dd00: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
dd10: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
dd20: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
dd30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
dd40: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dd50: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
dd60: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
dd70: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
dd80: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
dd90: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
dda0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
ddb0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
ddc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
ddd0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
dde0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
ddf0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
de00: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
de10: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
de20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de30: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
de40: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
de50: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
de60: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
de70: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
de80: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
de90: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
dea0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
deb0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
dec0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
ded0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
dee0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
def0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
df00: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
df10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
df20: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
df30: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
df40: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
df50: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
df60: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
df70: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
df80: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
df90: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
dfa0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
dfb0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
dfc0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
dfd0: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
dfe0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
dff0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
e000: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
e010: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e020: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e030: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
e040: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e050: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
e060: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e070: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e080: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
e090: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e0a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e0b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e0c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e0d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e0e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e0f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e100: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
e110: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
e120: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
e130: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
e140: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e150: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e160: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
e170: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
e180: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e190: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
e1a0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
e1b0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
e1c0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
e1d0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
e1e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
e1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e200: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
e210: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e220: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
e230: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e240: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
e250: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
e260: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e270: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e280: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e290: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e2a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e2b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e2d0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
e2e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e2f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e300: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e310: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e320: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
e330: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
e340: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
e350: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
e360: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
e370: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e380: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
e390: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
e3a0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
e3b0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
e3c0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
e3d0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
e3e0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
e3f0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
e400: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e410: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
e420: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e430: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
e440: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
e450: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
e460: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
e470: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
e480: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
e490: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
e4a0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
e4b0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
e4c0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
e4d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e4e0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
e4f0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
e500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
e510: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
e520: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
e530: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
e540: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
e550: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
e560: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e570: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
e580: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
e590: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
e5a0: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
e5b0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
e5c0: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
e5d0: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
e5e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
e5f0: 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
e600: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
e610: 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
e620: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
e630: 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
e640: 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
e650: 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
e660: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
e670: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
e680: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
e690: 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
e6a0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e6b0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
e6c0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
e6d0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
e6e0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
e6f0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
e700: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
e710: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
e720: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
e730: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
e740: 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
e750: 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
e760: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
e770: 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
e780: 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  rach allocations
e790: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
e7a0: 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
e7b0: 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
e7c0: 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
e7d0: 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
e7e0: 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
e7f0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
e800: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
e810: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
e820: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
e830: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e840: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
e850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
e860: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
e870: 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
e880: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
e890: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
e8a0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
e8b0: 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
e8c0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
e8d0: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
e8e0: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
e8f0: 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
e900: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
e910: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
e920: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
e930: 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
e940: 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
e950: 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
e960: 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
e970: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
e980: 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
e990: 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
e9a0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
e9b0: 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
e9c0: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
e9d0: 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
e9e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
e9f0: 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
ea00: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
ea10: 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
ea20: 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
ea30: 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
ea40: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
ea50: 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
ea60: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
ea70: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
ea80: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
ea90: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
eaa0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
eab0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
eac0: 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
ead0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
eae0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
eaf0: 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
eb00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
eb10: 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
eb20: 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
eb30: 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
eb40: 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
eb50: 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
eb60: 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
eb70: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
eb80: 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
eb90: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
eba0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
ebb0: 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
ebc0: 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
ebd0: 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
ebe0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
ebf0: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
ec00: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
ec10: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
ec20: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
ec30: 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
ec40: 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
ec50: 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
ec60: 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
ec70: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
ec80: 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
ec90: 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
eca0: 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
ecb0: 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
ecc0: 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
ecd0: 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
ece0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
ecf0: 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
ed00: 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
ed10: 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
ed20: 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
ed30: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
ed40: 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
ed50: 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
ed60: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
ed70: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
ed80: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
ed90: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
eda0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
edb0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
edc0: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
edd0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
ede0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
edf0: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
ee00: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
ee10: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
ee20: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
ee30: 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
ee40: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
ee50: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
ee60: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
ee70: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ee80: 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
ee90: 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
eea0: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
eeb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
eec0: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
eed0: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
eee0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
eef0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ef00: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
ef10: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
ef20: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
ef30: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
ef40: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
ef50: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
ef60: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ef70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
ef80: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
ef90: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
efa0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
efb0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
efc0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
efd0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
efe0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
eff0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f000: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
f010: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
f020: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
f030: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
f040: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
f050: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
f060: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
f070: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
f080: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
f090: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
f0a0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
f0b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
f0c0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
f0d0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
f0e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
f0f0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
f100: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
f110: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
f120: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
f130: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
f140: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
f150: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
f160: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
f170: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
f180: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
f190: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
f1a0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
f1b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
f1c0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
f1d0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
f1e0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
f1f0: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
f200: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
f210: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
f220: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
f230: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
f240: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
f250: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
f260: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
f270: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
f280: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
f290: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f2a0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
f2b0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
f2c0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
f2d0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
f2e0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
f2f0: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
f300: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
f310: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
f320: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
f330: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f340: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
f350: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f360: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f370: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f380: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f390: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
f3a0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
f3b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f3c0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
f3d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
f3e0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
f3f0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
f400: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
f410: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
f420: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
f430: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
f440: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
f450: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
f460: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
f470: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
f480: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f490: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
f4a0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
f4b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f4c0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
f4d0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
f4e0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
f4f0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
f500: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
f510: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
f520: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
f530: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
f540: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
f550: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
f560: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
f570: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
f580: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f590: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
f5a0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
f5b0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
f5c0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
f5d0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
f5e0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
f5f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f600: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f610: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f620: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f630: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f640: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f650: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
f660: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
f670: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
f680: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
f690: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
f6a0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f6b0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
f6c0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
f6d0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
f6e0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
f6f0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
f700: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
f710: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
f720: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
f730: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
f740: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
f750: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
f760: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
f770: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
f780: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
f790: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
f7a0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
f7b0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f7c0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f7d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f7e0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f7f0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f800: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f810: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
f820: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
f830: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
f840: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
f850: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
f860: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f870: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
f880: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
f890: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
f8a0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
f8b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f8c0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
f8d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f8e0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
f8f0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f900: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
f910: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
f920: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
f930: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
f940: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
f950: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
f960: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
f970: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
f980: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
f990: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
f9a0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
f9b0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
f9c0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
f9d0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
f9e0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
f9f0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
fa00: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
fa10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fa20: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
fa30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
fa40: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
fa50: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
fa60: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
fa70: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
fa80: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
fa90: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
faa0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
fab0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
fac0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
fad0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
fae0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
faf0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
fb00: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
fb10: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
fb20: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
fb30: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
fb40: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
fb50: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
fb60: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
fb70: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
fb80: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
fb90: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
fba0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
fbb0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
fbc0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
fbd0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
fbe0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
fbf0: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
fc00: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
fc10: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
fc20: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
fc30: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fc40: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
fc50: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
fc60: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
fc70: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
fc80: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
fc90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
fca0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
fcb0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
fcc0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
fcd0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
fce0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
fcf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
fd00: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
fd10: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
fd20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fd30: 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
fd40: 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
fd50: 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
fd60: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
fd70: 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
fd80: 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
fd90: 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
fda0: 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
fdb0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
fdc0: 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
fdd0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
fde0: 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
fdf0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
fe00: 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
fe10: 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
fe20: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
fe30: 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
fe40: 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
fe50: 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
fe60: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
fe70: 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
fe80: 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
fe90: 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
fea0: 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
feb0: 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
fec0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
fed0: 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
fee0: 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
fef0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
ff00: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
ff10: 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
ff20: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
ff30: 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
ff40: 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
ff50: 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
ff60: 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
ff70: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
ff80: 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
ff90: 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
ffa0: 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
ffb0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
ffc0: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
ffd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
ffe0: 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
fff0: 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
10000 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
10010 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
10020 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
10030 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
10040 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
10050 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
10060 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
10070 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
10080 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
10090 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
100a0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
100b0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
100c0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
100d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
100e0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
100f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
10100 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
10110 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
10120 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
10130 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
10140 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
10150 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
10160 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
10170 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
10180 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
10190 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
101a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
101b0 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
101c0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
101d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
101e0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
101f0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10210 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
10220 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
10230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10240 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
10250 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
10260 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
10270 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10280 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
10290 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
102a0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
102b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
102c0 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
102d0 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
102e0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
102f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10300 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
10310 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
10320 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
10330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10340 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
10350 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
10360 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
10370 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
10380 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10390 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
103a0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
103b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
103c0 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
103d0 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
103e0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
103f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10400 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
10410 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
10420 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10430 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
10440 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
10450 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
10460 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
10470 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
10480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10490 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
104a0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
104b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
104c0 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
104d0 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
104e0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
104f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10500 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
10510 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
10520 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
10530 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
10540 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
10550 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
10560 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
10570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10580 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
10590 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
105a0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
105b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
105c0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
105d0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
105e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105f0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
10600 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
10610 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10620 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
10630 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
10640 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
10650 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10660 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
10670 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
10680 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
10690 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
106a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
106b0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
106c0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
106d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
106e0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
106f0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
10700 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10710 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
10720 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
10730 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
10740 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10750 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
10760 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
10770 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10780 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
10790 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
107a0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
107b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
107c0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
107d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
107e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
107f0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
10800 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10810 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
10820 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
10830 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
10840 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
10850 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
10860 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
10870 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
10880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10890 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
108a0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
108b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
108c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
108d0 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
108e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
108f0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
10900 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
10910 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
10920 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10930 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
10940 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10950 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
10960 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
10970 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
10980 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
10990 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
109a0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
109b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
109c0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
109d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
109e0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
109f0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
10a00 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
10a10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
10a20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
10a30 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
10a40 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
10a50 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
10a60 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
10a70 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
10a80 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
10a90 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
10aa0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
10ab0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
10ac0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
10ad0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
10ae0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
10af0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
10b00 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
10b10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10b20 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
10b30 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
10b40 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
10b50 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
10b60 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
10b70 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
10b80 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
10b90 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
10ba0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
10bb0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
10bc0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
10bd0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
10be0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
10bf0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
10c00 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
10c10 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
10c20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
10c30 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
10c40 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
10c50 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
10c60 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
10c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10c80 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
10c90 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
10ca0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
10cb0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
10cc0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
10cd0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
10ce0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
10cf0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
10d00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
10d10 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
10d20 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
10d30 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
10d40 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
10d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
10d60 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10d70 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
10d80 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f  * int int */.../
10d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
10da0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
10db0 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
10dc0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
10dd0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
10de0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
10df0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
10e00 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
10e10 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
10e20 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
10e30 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
10e40 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
10e50 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
10e60 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
10e70 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
10e80 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
10e90 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
10ea0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
10eb0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
10ec0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
10ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10ee0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
10ef0 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
10f00 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
10f10 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
10f20 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
10f30 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
10f40 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
10f50 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
10f60 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
10f70 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
10f80 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
10f90 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
10fa0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
10fb0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
10fc0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
10fd0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
10fe0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
10ff0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
11000 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
11010 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
11020 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
11030 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
11040 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
11050 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
11060 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
11070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
11080 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
11090 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
110a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
110b0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
110c0 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
110d0 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
110e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
110f0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
11100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
11110 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
11120 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
11130 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
11140 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
11150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
11160 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
11170 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
11180 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
11190 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
111a0 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64   then the [rowid
111b0 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
111c0 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
111d0 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
111e0 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
111f0 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
11200 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
11210 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
11220 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
11230 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11240 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
11250 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
11260 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
11270 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
11280 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e  trigger fired.)^
11290 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
112a0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
112b0 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
112c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
112d0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
112e0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
112f0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
11300 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
11310 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
11320 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
11330 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
11340 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
11350 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
11360 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
11370 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
11380 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
11390 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
113a0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
113b0 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
113c0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
113d0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
113e0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
113f0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
11400 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
11410 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
11420 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
11430 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
11440 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
11450 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
11460 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
11470 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
11480 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
11490 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
114a0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
114b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
114c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
114d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
114e0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
114f0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
11500 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
11510 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
11520 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
11530 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
11540 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
11550 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
11560 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
11570 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
11580 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
11590 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
115a0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
115b0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
115c0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
115d0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
115e0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
115f0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
11600 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
11610 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
11620 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11630 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
11640 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
11650 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
11660 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
11670 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
11680 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11690 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
116a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
116b0 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
116c0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
116d0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
116e0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
116f0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
11700 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
11710 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
11720 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
11730 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
11740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11750 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
11760 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
11770 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
11780 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11790 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
117a0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
117b0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
117c0 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
117d0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
117e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
117f0 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
11800 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
11810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11820 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
11830 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
11840 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
11850 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
11860 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
11870 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
11880 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
11890 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
118a0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
118b0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
118c0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
118d0 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
118e0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
118f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
11900 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
11910 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
11920 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11930 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
11940 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
11950 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
11960 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
11970 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
11980 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
11990 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
119a0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
119b0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
119c0 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
119d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
119e0 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
119f0 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
11a00 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
11a10 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
11a20 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
11a30 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
11a40 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
11a50 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
11a60 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
11a70 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
11a80 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
11a90 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
11aa0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
11ab0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
11ac0 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
11ad0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
11ae0 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
11af0 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
11b00 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
11b10 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
11b20 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
11b30 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
11b40 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
11b50 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
11b60 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
11b70 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
11b80 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
11b90 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
11ba0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
11bb0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
11bc0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
11bd0 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
11be0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
11bf0 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
11c00 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
11c10 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
11c20 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
11c30 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
11c40 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
11c50 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
11c60 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
11c70 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
11c80 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
11c90 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
11ca0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
11cb0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
11cc0 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
11cd0 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
11ce0 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
11cf0 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
11d00 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
11d10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
11d20 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
11d30 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
11d40 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
11d50 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
11d60 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11d70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
11d80 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
11d90 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
11da0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
11db0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
11dc0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
11dd0 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
11de0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
11df0 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
11e00 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
11e10 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
11e20 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
11e30 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
11e40 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
11e50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
11e60 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
11e70 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
11e80 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
11e90 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
11ea0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
11eb0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
11ec0 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
11ed0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
11ee0 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
11ef0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
11f00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
11f10 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
11f20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
11f30 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
11f40 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
11f50 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
11f60 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
11f70 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
11f80 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
11f90 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
11fa0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
11fb0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
11fc0 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
11fd0 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
11fe0 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
11ff0 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
12000 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
12010 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
12020 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
12030 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
12040 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
12050 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
12060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
12070 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
12080 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
12090 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
120a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
120b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
120c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
120d0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
120e0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
120f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
12100 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12110 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
12120 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12130 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
12140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12150 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
12160 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
12170 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
12180 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
12190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
121a0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
121b0 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
121c0 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
121d0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
121e0 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
121f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12200 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
12210 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
12220 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
12230 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
12240 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
12250 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
12260 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
12270 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
12280 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
12290 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
122a0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
122b0 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
122c0 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
122d0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
122e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
122f0 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
12300 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
12310 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
12320 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
12330 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
12340 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
12350 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
12360 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
12370 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
12380 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
12390 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
123a0 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
123b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
123c0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
123d0 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
123e0 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
123f0 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
12400 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
12410 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
12420 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
12430 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
12440 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
12450 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
12460 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
12470 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
12480 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
12490 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
124a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
124b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
124c0 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
124d0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
124e0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
124f0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
12500 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
12510 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
12520 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
12530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
12540 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
12550 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
12560 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
12570 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
12580 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
12590 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
125a0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
125b0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
125c0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
125d0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
125e0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
125f0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
12600 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12610 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
12620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
12630 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
12640 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
12650 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12660 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
12670 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
12680 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
12690 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
126a0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
126b0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
126c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
126d0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
126e0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
126f0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
12700 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
12710 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
12720 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
12730 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
12740 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
12750 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
12760 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
12770 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
12780 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
12790 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
127a0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
127b0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
127c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
127d0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
127e0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
127f0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
12800 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
12810 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
12820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12830 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
12840 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
12850 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
12860 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12870 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
12880 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
12890 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
128a0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
128b0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
128c0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
128d0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
128e0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
128f0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
12900 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
12910 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
12920 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
12930 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
12940 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
12950 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
12960 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
12970 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
12980 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
12990 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
129a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
129b0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
129c0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
129d0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
129e0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
129f0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
12a00 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
12a10 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
12a20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
12a30 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
12a40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12a50 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
12a60 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
12a70 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
12a80 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
12a90 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
12aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12ab0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
12ac0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
12ad0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12ae0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12af0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
12b00 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
12b10 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
12b20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
12b30 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
12b40 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
12b50 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
12b60 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
12b70 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
12b80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12b90 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
12ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
12bb0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
12bc0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
12bd0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
12be0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
12bf0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
12c00 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
12c10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12c20 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
12c30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12c40 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
12c50 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
12c60 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
12c70 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
12c80 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
12c90 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
12ca0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12cb0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12cc0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
12cd0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
12ce0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
12cf0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
12d00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
12d10 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
12d20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
12d30 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
12d40 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
12d50 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
12d60 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
12d70 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
12d80 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
12d90 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
12da0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
12db0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
12dc0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
12dd0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
12de0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
12df0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
12e00 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
12e10 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
12e20 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
12e30 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
12e40 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
12e50 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
12e60 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
12e70 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
12e80 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
12e90 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
12ea0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
12eb0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
12ec0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
12ed0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
12ee0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
12ef0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
12f00 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
12f10 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
12f20 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
12f30 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
12f40 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
12f50 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
12f60 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
12f70 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
12f80 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
12f90 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
12fa0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
12fb0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
12fc0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
12fd0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
12fe0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
12ff0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
13000 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
13010 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
13020 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
13030 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
13040 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
13050 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
13060 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
13070 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
13080 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
13090 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
130a0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
130b0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
130c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
130d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
130e0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
130f0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
13100 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
13110 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13120 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
13130 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
13140 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
13150 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
13160 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
13170 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
13180 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
13190 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
131a0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
131b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
131c0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
131d0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
131e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
131f0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
13200 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
13210 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13220 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
13230 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
13240 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
13250 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
13260 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
13270 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
13280 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
13290 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
132a0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
132b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
132c0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
132d0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
132e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
132f0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
13300 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
13310 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
13320 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
13330 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
13340 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13350 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
13360 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
13370 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
13380 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
13390 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
133a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
133b0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
133c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
133d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
133e0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
133f0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
13400 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13410 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
13420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13430 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
13440 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
13450 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
13460 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
13470 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
13480 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
13490 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
134a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
134b0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
134c0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
134d0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
134e0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
134f0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
13500 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
13510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
13520 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
13530 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
13540 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
13550 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
13560 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
13570 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
13580 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
13590 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
135a0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
135b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
135c0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
135d0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
135e0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
135f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
13600 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
13610 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
13620 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
13630 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
13640 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
13650 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
13660 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
13670 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
13680 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13690 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
136a0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
136b0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
136c0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
136d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
136e0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
136f0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
13700 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13710 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
13720 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
13730 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
13740 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
13750 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
13760 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
13770 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
13780 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13790 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
137a0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
137b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
137c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
137d0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
137e0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
137f0 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
13800 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
13810 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
13820 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
13830 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
13840 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
13850 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
13860 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
13870 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
13880 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
13890 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
138a0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
138b0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
138c0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
138d0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
138e0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
138f0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
13900 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13910 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
13920 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13930 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
13940 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
13950 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
13960 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
13970 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
13980 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13990 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
139a0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
139b0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
139c0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
139d0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
139e0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
139f0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
13a00 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
13a10 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
13a20 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
13a30 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
13a40 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
13a50 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
13a60 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
13a70 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
13a80 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
13a90 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
13aa0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
13ab0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
13ac0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
13ad0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
13ae0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
13af0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
13b00 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
13b10 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
13b20 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
13b30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
13b40 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
13b50 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
13b60 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
13b70 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
13b80 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
13b90 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
13ba0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
13bb0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
13bc0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
13bd0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
13be0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
13bf0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
13c00 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
13c10 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
13c20 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
13c30 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13c40 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
13c50 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
13c60 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
13c70 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
13c80 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
13c90 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
13ca0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
13cb0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
13cc0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
13cd0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
13ce0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
13cf0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
13d00 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
13d10 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
13d20 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
13d30 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
13d40 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
13d50 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
13d60 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
13d70 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
13d80 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
13d90 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
13da0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
13db0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
13dc0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
13dd0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
13de0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
13df0 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
13e00 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
13e10 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
13e20 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
13e30 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
13e40 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
13e50 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
13e60 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13e70 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
13e80 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
13e90 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
13ea0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
13eb0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
13ec0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
13ed0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
13ee0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
13ef0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13f00 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
13f10 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13f20 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
13f30 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
13f40 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
13f50 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
13f60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
13f70 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
13f80 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
13f90 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
13fa0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
13fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
13fc0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
13fd0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
13fe0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
13ff0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
14000 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
14010 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
14020 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
14030 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
14040 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
14050 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
14060 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
14070 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
14080 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
14090 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
140a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
140b0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
140c0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
140d0 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
140e0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
140f0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
14100 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
14110 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
14120 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
14130 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
14140 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
14150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14160 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
14170 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
14180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14190 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
141a0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
141b0 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
141c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
141d0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
141e0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
141f0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
14200 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
14210 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
14220 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
14230 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
14240 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
14250 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
14260 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
14270 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
14280 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
14290 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
142a0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
142b0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
142c0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
142d0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
142e0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
142f0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
14300 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
14310 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
14320 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
14330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14340 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
14350 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
14360 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14370 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
14380 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
14390 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
143a0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
143b0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
143c0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
143d0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
143e0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
143f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
14400 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
14410 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
14420 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14430 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
14440 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
14450 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
14460 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
14470 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
14480 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
14490 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
144a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
144b0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
144c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
144d0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
144e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
144f0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
14500 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
14510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14520 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
14530 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
14540 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
14550 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
14560 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
14570 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
14580 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
14590 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
145a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
145b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
145c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
145d0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
145e0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
145f0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
14600 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
14610 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
14620 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
14630 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
14640 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
14650 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
14660 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
14670 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14680 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
14690 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
146a0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
146b0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
146c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
146d0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
146e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
146f0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
14700 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
14710 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
14720 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
14730 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
14740 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
14750 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
14760 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
14770 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
14780 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
14790 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
147a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
147b0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
147c0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
147d0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
147e0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
147f0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
14800 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
14810 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
14820 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
14830 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
14840 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
14850 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
14860 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
14870 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
14880 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
14890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
148a0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
148b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
148c0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
148d0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
148e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
148f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
14900 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
14910 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
14920 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
14930 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
14940 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
14950 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
14960 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
14970 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
14980 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
14990 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
149a0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
149b0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
149c0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
149d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
149e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
149f0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
14a00 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
14a10 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
14a20 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
14a30 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
14a40 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
14a50 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
14a60 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
14a70 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
14a80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14a90 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
14aa0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
14ab0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
14ac0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
14ad0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
14ae0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
14af0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
14b00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
14b10 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
14b20 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
14b30 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
14b40 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
14b50 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
14b60 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
14b70 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
14b80 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
14b90 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
14ba0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
14bb0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
14bc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14bd0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
14be0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14bf0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
14c00 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14c10 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
14c20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14c30 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
14c40 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
14c50 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
14c60 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
14c70 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14c80 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
14c90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14ca0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e>.**.** ^The sq
14cb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14cc0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
14cd0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
14ce0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
14cf0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
14d00 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
14d10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
14d20 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
14d30 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
14d40 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
14d50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
14d60 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
14d70 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
14d80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
14d90 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
14da0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
14db0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
14dc0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
14dd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
14de0 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73  * it should pass
14df0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
14e00 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
14e10 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
14e20 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
14e30 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
14e40 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
14e50 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
14e60 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
14e70 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
14e80 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
14e90 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
14ea0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
14eb0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
14ec0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
14ed0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
14ee0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
14ef0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
14f00 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
14f10 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
14f20 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
14f30 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
14f40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
14f50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14f60 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
14f70 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
14f80 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
14f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
14fa0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
14fb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
14fc0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
14fd0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
14fe0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
14ff0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
15000 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
15010 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
15020 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
15030 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
15040 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
15050 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
15060 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
15070 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
15080 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
15090 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
150a0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
150b0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
150c0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
150d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
150e0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
150f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
15100 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ].)^.*/.int sqli
15110 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
15120 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
15130 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
15140 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
15150 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
15160 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
15170 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
15180 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
15190 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
151a0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
151b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
151c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
151d0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
151e0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
151f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
15200 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
15210 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
15220 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
15230 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
15240 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
15250 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
15260 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
15270 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
15280 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
15290 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
152a0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
152b0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
152c0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
152d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
152e0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
152f0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
15300 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
15310 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
15320 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
15330 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
15340 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
15350 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
15360 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
15370 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
15380 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
15390 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
153a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
153b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
153c0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
153d0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
153e0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
153f0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
15400 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15410 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
15420 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
15430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
15440 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15450 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
15460 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
15470 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
15480 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
15490 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  tring..**.** ^(I
154a0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
154b0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
154c0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
154d0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
154e0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
154f0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
15500 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
15510 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
15520 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
15530 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15540 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
15550 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
15560 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15570 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
15580 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
15590 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
155a0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
155b0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
155c0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
155d0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
155e0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
155f0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
15600 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
15610 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15620 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
15630 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
15640 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
15650 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
15660 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
15670 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
15680 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
15690 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
156a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
156b0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
156c0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
156d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
156e0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
156f0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
15700 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
15710 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
15720 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
15730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15740 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15750 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
15760 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
15770 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
15780 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
15790 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
157a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
157b0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
157c0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
157d0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
157e0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
157f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
15800 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
15810 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
15820 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
15830 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
15840 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
15850 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
15860 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
15870 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
15880 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
15890 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
158a0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
158b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
158c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
158d0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
158e0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
158f0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
15900 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
15910 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
15920 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
15930 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
15940 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
15950 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
15960 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
15970 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
15980 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
15990 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
159a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
159b0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
159c0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
159d0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
159e0 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
159f0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
15a00 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
15a10 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
15a20 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
15a30 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
15a40 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
15a50 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
15a60 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
15a70 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
15a80 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
15a90 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
15aa0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
15ab0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
15ac0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
15ad0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
15ae0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
15af0 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
15b00 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
15b10 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
15b20 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
15b30 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15b40 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
15b50 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
15b60 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
15b70 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15b80 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
15b90 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
15ba0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
15bb0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
15bc0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
15bd0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15be0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
15bf0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
15c00 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15c10 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
15c20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
15c30 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
15c40 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
15c50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
15c60 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
15c70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15c80 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
15c90 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
15ca0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
15cb0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
15cc0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
15cd0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
15ce0 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
15cf0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
15d00 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15d10 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
15d20 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
15d30 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
15d40 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
15d50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15d60 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
15d70 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
15d80 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
15d90 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
15da0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
15db0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
15dc0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15dd0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
15de0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
15df0 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
15e00 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
15e10 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15e20 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
15e30 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
15e40 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
15e50 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
15e60 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
15e70 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
15e80 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
15e90 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
15ea0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
15eb0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
15ec0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
15ed0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
15ee0 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
15ef0 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
15f00 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
15f10 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
15f20 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
15f30 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
15f40 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15f50 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
15f60 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
15f70 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
15f80 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
15f90 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
15fa0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
15fb0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
15fc0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
15fd0 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
15fe0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
15ff0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
16000 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
16010 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
16020 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
16030 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
16040 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
16050 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
16060 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
16070 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
16080 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16090 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
160a0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
160b0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
160c0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
160d0 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
160e0 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
160f0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
16100 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
16110 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
16120 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
16130 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
16140 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
16150 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
16160 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
16170 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
16180 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
16190 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
161a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
161b0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
161c0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
161d0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
161e0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
161f0 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
16200 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
16210 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
16220 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
16230 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
16240 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
16250 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
16260 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
16270 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
16280 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
16290 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
162a0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
162b0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
162c0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
162d0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
162e0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
162f0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
16300 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
16310 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
16320 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
16330 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
16340 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
16350 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
16360 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
16370 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
16380 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
16390 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
163a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
163b0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
163c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
163d0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
163e0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
163f0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
16400 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
16410 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
16420 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
16430 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
16440 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
16450 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
16460 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
16470 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16480 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
16490 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
164a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
164b0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
164c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
164d0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
164e0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
164f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
16500 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16510 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
16520 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
16530 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
16540 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
16550 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
16560 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
16570 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
16580 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
16590 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
165a0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
165b0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
165c0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
165d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
165e0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
165f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
16600 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
16610 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
16620 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
16630 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
16640 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
16650 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
16660 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
16670 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
16680 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
16690 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
166a0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
166b0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
166c0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
166d0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
166e0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
166f0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
16700 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
16710 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
16720 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
16730 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
16740 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
16750 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
16760 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
16770 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16780 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
16790 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
167a0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
167b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
167c0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
167d0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
167e0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
167f0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
16800 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
16810 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
16820 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
16830 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
16840 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
16850 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
16860 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
16870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
16880 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
16890 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
168a0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
168b0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
168c0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
168d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
168e0 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
168f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16900 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16910 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
16920 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16930 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16940 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
16950 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
16960 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
16970 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
16980 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
16990 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
169a0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
169b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
169c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
169d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
169e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
169f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
16a00 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
16a10 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
16a20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
16a30 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
16a40 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
16a50 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
16a60 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
16a70 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
16a80 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16a90 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
16aa0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
16ab0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16ac0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
16ad0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
16ae0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
16af0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
16b00 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
16b10 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
16b20 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
16b30 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
16b40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
16b50 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
16b60 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
16b70 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
16b80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
16b90 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
16ba0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16bb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
16bc0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
16bd0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
16be0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
16bf0 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a   boundary..**.**
16c00 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
16c10 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
16c20 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
16c30 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
16c40 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
16c50 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
16c60 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
16c70 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
16c80 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
16c90 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
16ca0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
16cb0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
16cc0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
16cd0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
16ce0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
16cf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
16d00 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
16d10 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
16d20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
16d30 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
16d40 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
16d50 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
16d60 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
16d70 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
16d80 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
16d90 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
16da0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
16db0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
16dc0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
16dd0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
16de0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
16df0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
16e00 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
16e10 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
16e20 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
16e30 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
16e40 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
16e50 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
16e60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
16e70 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
16e80 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
16e90 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
16ea0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
16eb0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
16ec0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16ed0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
16ee0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
16ef0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
16f00 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
16f10 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
16f20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
16f30 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
16f40 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
16f50 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
16f60 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
16f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
16f80 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
16f90 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
16fa0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
16fb0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
16fc0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
16fd0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
16fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
16ff0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17000 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
17010 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
17020 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
17030 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17040 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
17050 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
17060 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17070 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
17080 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
17090 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
170a0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
170b0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
170c0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
170d0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
170e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
170f0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
17100 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
17110 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17120 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
17130 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
17140 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
17150 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
17160 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
17170 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
17180 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
17190 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
171a0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
171b0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
171c0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
171d0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
171e0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
171f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17200 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
17210 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
17220 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
17230 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
17240 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
17250 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
17260 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
17270 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
17280 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
17290 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
172a0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
172b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
172c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
172d0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
172e0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
172f0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
17300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17310 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17320 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
17330 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
17340 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
17350 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
17360 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
17370 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
17380 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
17390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
173a0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
173b0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
173c0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
173d0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
173e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
173f0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
17400 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
17410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
17420 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
17430 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
17440 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
17450 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
17460 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
17470 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
17480 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
17490 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
174a0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
174b0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
174c0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
174d0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
174e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
174f0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
17500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17510 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
17520 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
17530 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
17540 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
17550 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
17560 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
17570 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
17580 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
17590 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
175a0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
175b0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
175c0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
175d0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
175e0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
175f0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
17600 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
17610 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
17620 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
17630 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
17640 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
17650 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
17660 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
17670 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
17680 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
17690 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
176a0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
176b0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
176c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
176d0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
176e0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
176f0 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
17700 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
17710 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
17720 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
17730 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
17740 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
17750 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
17760 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
17770 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
17780 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
17790 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
177a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
177b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
177c0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
177d0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
177e0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
177f0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
17800 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
17810 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
17820 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
17830 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
17840 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
17850 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
17860 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
17870 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
17880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17890 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
178a0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
178b0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
178c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
178d0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
178e0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
178f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
17900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17910 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
17920 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
17930 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
17940 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17950 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
17960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17970 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
17980 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
17990 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
179a0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
179b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
179c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
179d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
179e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
179f0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
17a00 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
17a10 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
17a20 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
17a30 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
17a40 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
17a50 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
17a60 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
17a70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17a80 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
17a90 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
17aa0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
17ab0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
17ac0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17ad0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
17ae0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
17af0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
17b00 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
17b10 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
17b20 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
17b30 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
17b40 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
17b50 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
17b60 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
17b70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
17b80 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
17b90 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
17ba0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
17bb0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
17bc0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
17bd0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17be0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
17bf0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
17c00 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
17c10 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
17c20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
17c30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
17c40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17c50 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
17c60 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
17c70 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
17c80 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
17c90 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
17ca0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
17cb0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
17cc0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17cd0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
17ce0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
17cf0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
17d00 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
17d10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
17d20 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
17d30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
17d40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
17d50 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
17d60 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
17d70 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
17d80 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
17d90 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
17da0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
17db0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
17dc0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
17dd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17de0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17df0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
17e00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
17e10 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
17e20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
17e30 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
17e40 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
17e50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17e60 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
17e70 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17e80 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
17e90 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
17ea0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
17eb0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
17ec0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
17ed0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
17ee0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
17ef0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
17f00 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
17f10 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
17f20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
17f30 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
17f40 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
17f50 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
17f60 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
17f70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
17f80 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
17f90 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
17fa0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
17fb0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17fc0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
17fd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
17fe0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
17ff0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
18000 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
18010 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
18020 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
18030 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
18040 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
18050 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
18060 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
18070 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
18080 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18090 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
180a0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
180b0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
180c0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
180d0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
180e0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
180f0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
18100 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
18110 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
18120 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
18130 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
18140 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
18150 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
18160 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
18170 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
18180 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
18190 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
181a0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
181b0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
181c0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
181d0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
181e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
181f0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
18200 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
18210 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
18220 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
18230 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
18240 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
18250 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
18260 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
18270 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
18280 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
18290 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
182a0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
182b0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
182c0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
182d0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
182e0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
182f0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
18300 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
18310 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
18320 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
18330 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
18340 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
18350 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
18360 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
18370 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
18380 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
18390 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
183a0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
183b0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
183c0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
183d0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
183e0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
183f0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
18400 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
18410 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
18420 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
18430 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
18440 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
18450 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
18460 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
18470 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
18480 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
18490 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
184a0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
184b0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
184c0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
184d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
184e0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
184f0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
18500 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
18510 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
18520 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
18530 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
18540 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
18550 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
18560 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
18570 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
18580 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
18590 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
185a0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
185b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
185c0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
185d0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
185e0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
185f0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
18600 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
18610 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
18620 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
18630 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
18640 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
18650 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
18660 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
18670 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
18680 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
18690 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
186a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
186b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
186c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
186d0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
186e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
186f0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
18700 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
18710 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
18720 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
18730 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
18740 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
18750 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
18760 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
18770 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
18780 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
18790 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
187a0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
187b0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
187c0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
187d0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
187e0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
187f0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
18800 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
18810 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
18820 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
18830 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
18840 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18850 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
18860 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
18870 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
18880 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
18890 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
188a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
188b0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
188c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
188d0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
188e0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
188f0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
18900 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
18910 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
18920 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
18930 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
18940 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
18950 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
18960 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
18970 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
18980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
18990 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
189a0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
189b0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
189c0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
189d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
189e0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
189f0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
18a00 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
18a10 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
18a20 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
18a30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
18a40 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
18a50 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
18a60 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
18a70 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
18a80 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
18a90 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
18aa0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18ab0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
18ac0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
18ad0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
18ae0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
18af0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
18b00 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
18b10 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
18b20 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
18b30 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
18b40 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
18b50 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18b60 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
18b70 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
18b80 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
18b90 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
18ba0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
18bb0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
18bc0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
18bd0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
18be0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
18bf0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
18c00 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
18c10 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
18c20 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
18c30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
18c40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
18c50 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
18c60 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
18c70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18c80 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
18c90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
18ca0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18cb0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
18cc0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
18cd0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
18ce0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
18cf0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
18d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18d10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
18d20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
18d30 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
18d40 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
18d50 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
18d60 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
18d70 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
18d80 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
18d90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18da0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
18db0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
18dc0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
18dd0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
18de0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
18df0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
18e00 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
18e10 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
18e20 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
18e30 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
18e40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
18e50 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
18e60 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
18e70 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
18e80 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
18e90 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
18ea0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
18eb0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
18ec0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
18ed0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18ee0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
18ef0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
18f00 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
18f10 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
18f20 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
18f30 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
18f40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18f50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
18f60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
18f70 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
18f80 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
18f90 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
18fa0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
18fb0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
18fc0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
18fd0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
18fe0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
18ff0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
19000 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
19010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
19030 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
19040 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
19050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19060 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
19070 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
19080 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
19090 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
190a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
190b0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
190c0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
190d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
190e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
190f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19100 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
19110 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
19120 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19130 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19150 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
19160 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
19170 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19180 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19190 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
191a0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
191b0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
191c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
191d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
191e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
191f0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
19200 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
19210 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
19220 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19230 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19240 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19250 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
19260 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19270 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19280 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19290 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
192a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
192b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
192c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
192d0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
192e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
192f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19300 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19310 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19320 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
19330 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
19340 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19350 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
19360 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19370 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
19380 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
19390 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
193a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
193b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
193c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
193d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
193e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
193f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19400 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19410 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
19420 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
19430 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19440 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19460 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
19470 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
19480 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
19490 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
194a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
194c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
194d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
194e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
194f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19500 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
19510 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
19520 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19550 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
19560 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
19570 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19580 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19590 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
195a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
195b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
195c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
195d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
195e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
195f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
19600 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
19610 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
19620 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
19630 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
19640 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
19650 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
19660 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
19670 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19680 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
19690 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
196a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
196b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
196c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
196d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
196e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
196f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
19700 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
19710 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19720 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
19730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19740 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
19750 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
19760 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
19770 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
19780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
19790 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
197a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
197b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
197c0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
197d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
197e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
197f0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
19800 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19810 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
19820 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
19830 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
19840 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
19850 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19860 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
19870 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
19880 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19890 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
198a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
198b0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
198c0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
198d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
198e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
198f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19900 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
19910 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
19920 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19930 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19940 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19950 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
19960 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
19970 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19980 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
19990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199a0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
199b0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
199c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
199d0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
199e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
199f0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
19a00 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
19a10 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
19a20 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
19a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a40 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
19a50 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
19a60 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
19a70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19a80 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
19a90 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
19aa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19ab0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
19ac0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
19ad0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
19ae0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
19af0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
19b00 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
19b10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
19b20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
19b30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
19b40 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
19b50 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
19b60 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
19b70 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
19b80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
19b90 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
19ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19bb0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
19bc0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
19bd0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
19be0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
19bf0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
19c00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
19c10 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
19c20 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
19c30 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
19c40 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
19c50 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
19c60 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
19c70 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
19c80 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
19c90 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
19ca0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
19cb0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
19cc0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
19cd0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
19ce0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
19cf0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
19d00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19d10 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19d20 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
19d30 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
19d40 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
19d50 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
19d60 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
19d70 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
19d80 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
19d90 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
19da0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
19db0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
19dc0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
19dd0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
19de0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
19df0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
19e00 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
19e10 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
19e20 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
19e30 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
19e40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
19e50 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
19e60 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
19e70 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
19e80 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
19e90 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
19ea0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
19eb0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
19ec0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
19ed0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
19ee0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
19ef0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
19f00 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
19f10 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
19f20 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
19f30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
19f40 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
19f50 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
19f60 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
19f70 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
19f80 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
19f90 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
19fa0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
19fb0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
19fc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
19fd0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
19fe0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
19ff0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1a000 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1a010 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1a020 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1a030 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1a040 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1a050 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1a060 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1a070 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1a080 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
1a090 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
1a0a0 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a  function - the.*
1a0b0 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  * progress callb
1a0c0 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e  ack - that is in
1a0d0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1a0e0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a  ly during long.*
1a0f0 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  * running calls 
1a100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
1a110 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1a120 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ep()] and.** [sq
1a130 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a140 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  )].  An example 
1a150 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1a160 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1a170 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1a180 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1a190 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1a1a0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1a1b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a1c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1a1d0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1a1e0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1a1f0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1a200 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1a210 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1a220 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1a230 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1a240 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1a250 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a260 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1a270 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1a280 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1a290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a2a0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1a2b0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1a2c0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
1a2d0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1a2e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1a2f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1a300 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1a310 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1a320 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1a330 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1a340 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1a350 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
1a360 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1a370 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1a380 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1a390 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1a3a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a3b0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1a3c0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1a3d0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1a3e0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1a3f0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1a400 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
1a410 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
1a420 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72  e.** filename ar
1a430 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1a440 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1a450 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1a460 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1a470 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a490 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1a4a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1a4b0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1a4c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a4d0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1a4e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1a4f0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1a500 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1a510 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1a520 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1a530 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1a540 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1a550 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1a560 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1a570 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1a580 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1a590 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1a5a0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1a5b0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1a5c0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1a5d0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1a5e0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1a5f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a600 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1a610 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1a620 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1a630 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1a640 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1a650 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1a660 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1a670 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1a680 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1a690 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1a6a0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1a6b0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1a6c0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1a6d0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1a6e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1a6f0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1a700 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1a710 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1a720 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1a730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1a740 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1a750 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1a760 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1a770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1a780 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1a790 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1a7a0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1a7b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1a7c0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1a7d0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1a7e0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1a7f0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1a800 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1a810 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1a820 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1a830 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1a840 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a850 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1a860 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1a870 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1a880 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1a890 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1a8a0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1a8b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a8c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1a8d0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1a8e0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1a8f0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1a900 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1a910 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1a920 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1a930 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1a940 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1a950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1a960 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1a970 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1a980 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1a990 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1a9a0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1a9b0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1a9c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1a9d0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1a9e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a9f0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1aa00 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1aa10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1aa20 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e  REDCACHE],.** an
1aa30 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1aa40 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1aa50 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
1aa60 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
1aa70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1aa80 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1aa90 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1aaa0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1aab0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1aac0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1aad0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1aae0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1aaf0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1ab00 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1ab10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1ab20 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1ab30 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1ab40 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1ab50 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1ab60 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1ab70 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1ab80 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1ab90 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1aba0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1abb0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1abc0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1abd0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1abe0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1abf0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1ac00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1ac10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1ac20 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1ac30 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1ac40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1ac50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1ac60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1ac70 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1ac80 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1ac90 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
1aca0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1acb0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1acc0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1acd0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1ace0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1acf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1ad00 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1ad10 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1ad20 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1ad30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1ad40 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1ad50 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1ad60 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1ad70 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1ad80 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
1ad90 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1ada0 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
1adb0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
1adc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1add0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1ade0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a  N_FULLMUTEX],.**
1adf0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1ae00 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f  AREDCACHE] and/o
1ae10 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
1ae20 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1ae30 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  gs,.** then the 
1ae40 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1ae50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1ae60 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1ae70 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1ae80 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1ae90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aea0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1aeb0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1aec0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1aed0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1aee0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1aef0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1af00 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1af10 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1af20 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1af30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1af40 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1af50 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1af60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1af70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1af80 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1af90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1afa0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1afb0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1afc0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1afd0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1afe0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1aff0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1b000 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1b010 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1b020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b030 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1b040 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1b050 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1b060 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1b070 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1b080 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1b090 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1b0a0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1b0b0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1b0c0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1b0d0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1b0e0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1b0f0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1b100 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1b110 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1b120 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1b130 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1b140 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1b150 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1b160 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1b170 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1b180 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1b190 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1b1a0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1b1b0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1b1c0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1b1d0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1b1e0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1b1f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1b200 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1b210 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1b220 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1b230 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1b240 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1b250 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1b260 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1b270 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1b280 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1b290 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1b2a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1b2b0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1b2c0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1b2d0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1b2e0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1b2f0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1b300 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1b310 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1b320 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1b330 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1b340 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1b350 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1b360 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1b370 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1b380 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1b390 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1b3a0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1b3b0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1b3c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b3d0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1b3e0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1b3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1b400 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  closed..**.** ^T
1b410 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b420 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1b430 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1b440 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1b450 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b460 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1b470 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1b480 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1b490 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1b4a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b4b0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1b4c0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1b4d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1b4e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1b4f0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1b500 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1b510 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1b520 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1b530 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1b540 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1b550 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1b560 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1b570 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1b580 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1b590 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1b5a0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1b5b0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1b5c0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1b5d0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1b5e0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1b5f0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1b600 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1b610 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1b620 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1b630 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1b640 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1b650 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1b660 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73  n_v2()..*/.int s
1b670 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
1b680 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1b690 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1b6a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1b6b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1b6c0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1b6d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1b6e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1b6f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1b700 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1b710 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1b720 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1b730 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1b740 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1b750 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1b760 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1b770 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1b780 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1b790 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1b7a0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1b7b0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1b7c0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1b7d0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1b7e0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1b7f0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1b800 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1b810 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1b820 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1b830 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1b840 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1b850 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1b860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b870 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
1b880 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
1b890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1b8a0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1b8b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1b8c0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1b8d0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1b8e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1b8f0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1b900 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1b910 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1b920 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b930 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1b940 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1b950 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1b960 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1b970 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1b980 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1b990 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1b9a0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1b9b0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1b9c0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
1b9d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1b9e0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
1b9f0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
1ba00 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
1ba10 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
1ba20 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
1ba30 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1ba40 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
1ba50 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
1ba60 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
1ba70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ba80 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1ba90 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1baa0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1bab0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1bac0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1bad0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1bae0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1baf0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1bb00 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
1bb10 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
1bb20 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
1bb30 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
1bb40 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
1bb50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1bb60 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
1bb70 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
1bb80 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
1bb90 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
1bba0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
1bbb0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
1bbc0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
1bbd0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
1bbe0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
1bbf0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
1bc00 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
1bc10 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
1bc20 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1bc30 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
1bc40 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
1bc50 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
1bc60 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
1bc70 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
1bc80 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
1bc90 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
1bca0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
1bcb0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
1bcc0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
1bcd0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
1bce0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
1bcf0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
1bd00 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
1bd10 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
1bd20 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
1bd30 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
1bd40 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
1bd50 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
1bd60 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
1bd70 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
1bd80 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
1bd90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bda0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
1bdb0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1bdc0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
1bdd0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1bde0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
1bdf0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
1be00 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
1be10 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
1be20 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1be30 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
1be40 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
1be50 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
1be60 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
1be70 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
1be80 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1be90 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1bea0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1beb0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1bec0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1bed0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1bee0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1bef0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1bf00 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1bf10 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1bf20 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1bf30 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1bf40 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1bf50 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
1bf60 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1bf70 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1bf80 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1bf90 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1bfa0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1bfb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1bfc0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1bfd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bfe0 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1bff0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
1c000 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
1c010 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
1c020 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
1c030 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
1c040 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
1c050 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
1c060 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
1c070 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
1c080 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
1c090 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
1c0a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
1c0b0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
1c0c0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1c0d0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
1c0e0 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
1c0f0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
1c100 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
1c110 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
1c120 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
1c130 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
1c140 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
1c150 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c160 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1c170 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
1c180 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
1c190 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
1c1a0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
1c1b0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
1c1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1c1d0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
1c1e0 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
1c1f0 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
1c200 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
1c210 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
1c220 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1c230 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
1c240 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1c250 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
1c260 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
1c270 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
1c280 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
1c290 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1c2a0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
1c2b0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1c2c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
1c2d0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1c2e0 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
1c2f0 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
1c300 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
1c310 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
1c320 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1c330 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1c340 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
1c350 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
1c360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c370 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
1c380 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
1c390 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1c3a0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1c3b0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1c3c0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1c3d0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1c3e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1c3f0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1c400 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1c410 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c420 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1c430 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1c440 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1c450 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c460 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1c470 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1c480 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1c490 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1c4a0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1c4b0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1c4c0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1c4d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1c4e0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1c4f0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
1c500 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1c510 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1c520 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1c530 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1c540 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
1c550 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
1c560 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
1c570 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
1c580 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
1c590 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
1c5a0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
1c5b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
1c5c0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
1c5d0 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
1c5e0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
1c5f0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
1c600 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
1c610 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
1c620 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
1c630 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
1c640 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
1c650 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
1c660 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
1c670 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
1c680 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
1c690 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
1c6a0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
1c6b0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
1c6c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1c6d0 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
1c6e0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
1c6f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
1c700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1c710 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
1c720 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
1c730 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
1c740 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
1c750 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
1c760 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
1c770 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
1c780 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
1c790 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
1c7a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
1c7b0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
1c7c0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
1c7d0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1c7e0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1c7f0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1c800 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1c810 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1c820 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1c830 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1c840 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1c850 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1c860 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1c870 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1c880 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1c890 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
1c8a0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1c8b0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1c8c0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1c8d0 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1c8e0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1c8f0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1c900 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1c910 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1c920 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1c930 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1c940 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1c950 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1c960 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1c970 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1c980 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1c990 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1c9a0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1c9b0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1c9c0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1c9d0 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1c9e0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1c9f0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1ca00 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1ca10 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1ca20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1ca30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1ca40 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1ca50 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1ca60 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1ca70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1ca80 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1ca90 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1caa0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1cab0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1cac0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1cad0 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1cae0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1caf0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1cb00 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1cb10 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
1cb20 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
1cb30 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
1cb40 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
1cb50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1cb60 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
1cb70 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
1cb80 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1cb90 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1cba0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1cbb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1cbc0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1cbd0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1cbe0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1cbf0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1cc00 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1cc10 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1cc20 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1cc30 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1cc40 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1cc50 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1cc60 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1cc70 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1cc80 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1cc90 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1cca0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1ccb0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1ccc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1ccd0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1cce0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1ccf0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1cd00 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1cd10 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
1cd20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1cd30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1cd40 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1cd50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1cd60 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1cd70 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
1cd80 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
1cd90 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cda0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
1cdb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1cdc0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1cdd0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
1cde0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
1cdf0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
1ce00 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
1ce10 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
1ce20 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1ce30 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1ce40 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
1ce50 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
1ce60 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
1ce70 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1ce80 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1ce90 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
1cea0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
1ceb0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
1cec0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
1ced0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
1cee0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1cef0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1cf00 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1cf10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1cf20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1cf30 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1cf40 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1cf50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1cf60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1cf70 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
1cf80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1cf90 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
1cfa0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
1cfb0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
1cfc0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
1cfd0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
1cfe0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
1cff0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
1d000 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
1d010 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
1d020 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
1d030 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
1d040 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
1d050 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
1d060 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1d070 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1d080 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1d090 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d0a0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1d0b0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1d0c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d0d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1d0e0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1d0f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d100 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
1d110 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
1d120 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
1d130 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d140 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1d150 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1d160 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d170 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1d180 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1d190 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1d1a0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1d1b0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
1d1c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d1d0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1d1e0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
1d1f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d200 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
1d210 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
1d220 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1d230 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  ent.)^.**.** ^(<
1d240 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d250 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
1d260 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d270 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
1d280 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
1d290 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
1d2a0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1d2b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1d2c0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1d2d0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1d2e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d2f0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1d300 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1d310 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d320 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1d330 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1d340 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d350 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1d360 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1d370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d380 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1d390 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1d3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d3b0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1d3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1d3d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d3e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1d3f0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1d400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d410 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1d420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d430 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1d440 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1d450 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1d460 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1d470 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1d480 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1d490 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
1d4a0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1d4b0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1d4c0 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
1d4d0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1d4e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1d4f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
1d500 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1d510 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
1d520 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
1d530 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
1d540 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
1d550 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
1d560 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
1d570 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
1d580 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
1d590 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d5a0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
1d5b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d5c0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
1d5d0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
1d5e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1d5f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1d600 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
1d610 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
1d620 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
1d630 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
1d640 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
1d650 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
1d660 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
1d670 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
1d680 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
1d690 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1d6a0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
1d6b0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
1d6c0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
1d6d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1d6e0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
1d6f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
1d700 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
1d710 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
1d720 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
1d730 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1d740 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
1d750 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
1d760 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1d770 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1d780 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1d790 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1d7a0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1d7b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
1d7c0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1d7d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1d7e0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1d7f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1d800 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1d810 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
1d820 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1d830 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
1d840 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
1d850 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
1d860 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
1d870 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
1d880 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
1d890 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
1d8a0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
1d8b0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
1d8c0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
1d8d0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
1d8e0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
1d8f0 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
1d900 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
1d910 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
1d920 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
1d930 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
1d940 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
1d950 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
1d960 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1d970 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
1d980 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
1d990 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
1d9a0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
1d9b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  s..**.** ^If pzT
1d9c0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
1d9d0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
1d9e0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
1d9f0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
1da00 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
1da10 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1da20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1da30 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
1da40 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
1da50 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
1da60 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
1da70 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
1da80 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
1da90 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
1daa0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
1dab0 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
1dac0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
1dad0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
1dae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1daf0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
1db00 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
1db10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
1db20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
1db30 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1db40 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1db50 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
1db60 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1db70 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1db80 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1db90 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1dba0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1dbb0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1dbc0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
1dbd0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1dbe0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1dbf0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1dc00 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1dc10 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1dc20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1dc30 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1dc40 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1dc50 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
1dc60 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
1dc70 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
1dc80 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
1dc90 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
1dca0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1dcb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
1dcc0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
1dcd0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1dce0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1dcf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dd00 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1dd10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1dd20 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1dd30 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1dd40 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1dd50 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1dd60 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1dd70 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1dd80 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1dd90 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1dda0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1ddb0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
1ddc0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1ddd0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
1dde0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
1ddf0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
1de00 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
1de10 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
1de20 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
1de30 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
1de40 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
1de50 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
1de60 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
1de70 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
1de80 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
1de90 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
1dea0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
1deb0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
1dec0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1ded0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
1dee0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
1def0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
1df00 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
1df10 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
1df20 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
1df30 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1df40 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
1df50 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
1df60 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
1df70 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61 20   ^If the schema 
1df80 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
1df90 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
1dfa0 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
1dfb0 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
1dfc0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1dfd0 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
1dfe0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1dff0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
1e000 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
1e010 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
1e020 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
1e030 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
1e040 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
1e050 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e060 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
1e070 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
1e080 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
1e090 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
1e0a0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
1e0b0 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
1e0c0 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
1e0d0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
1e0e0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
1e0f0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
1e100 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1e110 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1e120 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1e130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1e140 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1e150 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1e160 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1e170 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1e180 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1e190 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1e1a0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1e1b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1e1c0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1e1d0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1e1e0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1e1f0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1e200 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1e210 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1e220 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1e230 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e240 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1e250 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1e260 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1e270 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1e280 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1e290 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1e2a0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1e2b0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1e2c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1e2d0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1e2e0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1e2f0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
1e300 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72   of a [parameter
1e310 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
1e320 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20  r] in the WHERE 
1e330 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20  clause might.** 
1e340 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 79  change the query
1e350 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
1e360 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  ement, then the 
1e370 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65  statement may be
1e380 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1e390 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73  y recompiled (as
1e3a0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
1e3b0 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  en a schema chan
1e3c0 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge) on the first
1e3d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
1e3e0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
1e3f0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20  wing any change 
1e400 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  to the .** [sqli
1e410 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1e420 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65  bindings] of the
1e430 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
1e440 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1e450 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e460 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1e470 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1e480 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1e490 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e4a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1e4b0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1e4c0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1e4d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1e4e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1e4f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1e500 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1e510 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1e520 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1e530 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1e540 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1e550 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1e560 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1e570 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1e580 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1e590 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1e5a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1e5b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e5c0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1e5d0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1e5e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1e5f0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1e600 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1e610 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1e620 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1e630 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1e640 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1e650 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1e660 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1e670 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1e680 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1e690 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1e6a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1e6b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1e6c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1e6d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1e6e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e6f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1e700 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1e710 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1e720 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e730 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1e740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e750 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1e760 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1e770 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1e780 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1e790 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1e7a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1e7b0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1e7c0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1e7d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e7e0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1e7f0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1e800 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1e810 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1e820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1e830 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1e840 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1e850 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1e860 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1e870 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1e880 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1e890 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1e8a0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e8b0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e8c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e8d0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e8e0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e8f0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e900 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e910 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e920 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1e930 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e940 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e950 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e960 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1e970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
1e980 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1e990 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
1e9a0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1e9b0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1e9c0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1e9d0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1e9e0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1e9f0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1ea00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ea10 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1ea20 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1ea30 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1ea40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1ea50 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1ea60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ea70 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
1ea80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1ea90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1eaa0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1eab0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
1eac0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
1ead0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1eae0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1eaf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1eb00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1eb10 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1eb20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1eb30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1eb40 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
1eb50 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
1eb60 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
1eb70 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
1eb80 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
1eb90 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1eba0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
1ebb0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
1ebc0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
1ebd0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1ebe0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
1ebf0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1ec00 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1ec10 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1ec20 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1ec30 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1ec40 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1ec50 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1ec60 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1ec70 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1ec80 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1ec90 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1eca0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1ecb0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1ecc0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1ecd0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1ece0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1ecf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1ed00 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1ed10 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1ed20 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1ed30 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1ed40 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
1ed50 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1ed60 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1ed70 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1ed80 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1ed90 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1eda0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1edb0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1edc0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1edd0 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1ede0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1edf0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1ee00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ee10 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1ee20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1ee30 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1ee40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ee50 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1ee60 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1ee70 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1ee80 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1ee90 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1eea0 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
1eeb0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1eec0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
1eed0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
1eee0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
1eef0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
1ef00 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
1ef10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
1ef20 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
1ef30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1ef40 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
1ef50 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
1ef60 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1ef70 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1ef80 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1ef90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1efa0 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
1efb0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
1efc0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
1efd0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
1efe0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
1eff0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
1f000 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1f010 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
1f020 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
1f030 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1f040 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1f050 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1f060 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1f070 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
1f080 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
1f090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f0a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f0b0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1f0c0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1f0d0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1f0e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1f0f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1f100 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1f110 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1f120 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f130 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1f140 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1f150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1f160 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1f170 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1f180 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f190 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1f1a0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1f1b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1f1c0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1f1d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1f1e0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1f1f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1f200 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1f210 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1f220 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1f230 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1f240 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1f250 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1f260 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1f270 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1f280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f290 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1f2a0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
1f2b0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
1f2c0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
1f2d0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
1f2e0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
1f2f0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
1f300 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
1f310 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1f320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1f330 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1f340 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1f350 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1f360 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1f370 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1f380 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1f390 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1f3a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1f3b0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1f3c0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1f3d0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1f3e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1f3f0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1f400 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1f410 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1f420 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1f430 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1f440 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1f450 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1f460 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1f470 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1f480 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1f490 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1f4a0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1f4b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1f4c0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1f4d0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1f4e0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1f4f0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1f500 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
1f510 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
1f520 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
1f530 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
1f540 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1f550 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
1f560 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
1f570 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
1f580 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
1f590 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
1f5a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1f5b0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
1f5c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f5d0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
1f5e0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
1f5f0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
1f600 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
1f610 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
1f620 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
1f630 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
1f640 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1f650 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
1f660 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
1f670 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
1f680 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
1f690 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
1f6a0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
1f6b0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
1f6c0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
1f6d0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1f6e0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
1f6f0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
1f700 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
1f710 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1f720 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1f730 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1f740 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1f750 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1f760 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1f770 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1f780 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f790 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1f7a0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1f7b0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1f7c0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1f7d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f7e0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
1f7f0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1f800 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1f810 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1f820 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1f830 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f840 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1f850 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
1f860 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1f870 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1f880 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1f890 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
1f8a0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1f8b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1f8c0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
1f8d0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
1f8e0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
1f8f0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1f900 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1f910 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1f920 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1f930 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1f940 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1f950 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
1f960 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
1f970 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1f980 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1f990 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1f9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f9b0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
1f9c0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
1f9d0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
1f9e0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
1f9f0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
1fa00 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
1fa10 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1fa20 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1fa30 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
1fa40 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
1fa50 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
1fa60 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1fa70 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
1fa80 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
1fa90 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
1faa0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
1fab0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
1fac0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1fad0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
1fae0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
1faf0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1fb00 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
1fb10 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1fb20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
1fb30 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
1fb40 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
1fb50 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1fb60 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1fb70 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
1fb80 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
1fb90 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
1fba0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
1fbb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1fbc0 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1fbd0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1fbe0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1fbf0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1fc00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1fc10 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1fc20 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
1fc30 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1fc40 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1fc50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1fc60 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1fc70 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1fc80 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1fc90 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1fca0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1fcb0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1fcc0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1fcd0 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20  ed with it. ^If 
1fce0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1fcf0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1fd00 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1fd10 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1fd20 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1fd30 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1fd40 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1fd50 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1fd60 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1fd70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1fd80 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
1fd90 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1fda0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1fdb0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1fdc0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1fdd0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1fde0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1fdf0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1fe00 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1fe10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fe20 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1fe30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1fe40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1fe50 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1fe60 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1fe70 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1fe80 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1fe90 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
1fea0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1feb0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1fec0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1fed0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1fee0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1fef0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1ff00 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1ff10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1ff20 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1ff30 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1ff40 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1ff50 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1ff60 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1ff70 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1ff80 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1ff90 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1ffa0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
1ffb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1ffc0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1ffd0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1ffe0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
1fff0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
20000 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
20010 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
20020 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
20030 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
20040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20050 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
20060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20070 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
20080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20090 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
200a0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
200b0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
200c0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
200d0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
200e0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
200f0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
20100 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
20110 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
20120 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20130 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
20140 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
20150 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
20160 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
20170 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
20180 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
20190 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
201a0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
201b0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
201c0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
201d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
201e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
201f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
20200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
20210 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
20220 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
20230 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
20240 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
20250 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
20260 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
20270 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
20280 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
20290 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
202a0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
202b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
202c0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
202d0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
202e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
202f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
20300 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
20310 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
20320 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
20330 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
20340 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
20350 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
20360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20370 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
20380 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20390 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
203a0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
203b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
203c0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
203d0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
203e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
203f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
20400 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
20410 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20420 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
20430 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
20440 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
20450 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
20460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20470 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20480 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
20490 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
204a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
204b0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
204c0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
204d0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
204e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
204f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
20500 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
20510 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20520 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
20530 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
20540 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
20550 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
20560 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
20570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20580 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
20590 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
205a0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
205b0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
205c0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
205d0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
205e0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
205f0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
20600 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
20610 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
20620 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
20630 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
20640 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
20650 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
20660 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
20670 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
20680 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
20690 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
206a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
206b0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
206c0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
206d0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
206e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
206f0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
20700 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
20710 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
20720 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
20730 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
20740 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
20750 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
20760 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
20770 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
20780 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
20790 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
207a0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
207b0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
207c0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
207d0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
207e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
207f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
20800 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
20810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20820 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
20830 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
20840 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20850 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
20860 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20870 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
20880 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
20890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
208a0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
208b0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
208c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
208d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
208e0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
208f0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
20900 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
20910 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
20920 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
20930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
20940 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
20950 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
20960 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
20970 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
20980 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
20990 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
209a0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
209b0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
209c0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
209d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
209e0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
209f0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
20a00 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
20a10 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
20a20 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
20a30 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
20a40 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
20a50 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
20a60 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
20a70 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
20a80 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
20a90 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
20aa0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
20ab0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
20ac0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
20ad0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
20ae0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
20af0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
20b00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
20b10 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
20b20 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
20b30 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
20b40 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
20b50 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
20b60 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
20b70 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
20b80 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
20b90 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
20ba0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
20bb0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
20bc0 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
20bd0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
20be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20bf0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
20c00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20c10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
20c20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
20c30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
20c40 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
20c50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20c60 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
20c70 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
20c80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
20c90 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
20ca0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
20cb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20cc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20cd0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
20ce0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
20cf0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
20d00 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
20d10 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
20d20 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
20d30 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
20d40 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
20d50 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
20d60 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
20d70 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
20d80 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
20d90 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
20da0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
20db0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
20dc0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
20dd0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
20de0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
20df0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
20e00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
20e10 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
20e20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
20e30 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
20e40 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
20e50 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
20e60 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
20e70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20e80 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
20e90 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20ea0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20eb0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20ec0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20ed0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
20ee0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
20ef0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20f00 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
20f10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
20f20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
20f30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
20f40 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
20f50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20f60 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
20f70 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
20f80 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
20f90 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
20fa0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
20fb0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
20fc0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
20fd0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
20fe0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20ff0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
21000 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
21010 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
21020 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
21030 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
21040 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
21050 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
21060 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
21070 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
21080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21090 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
210a0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
210b0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
210c0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
210d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
210e0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
210f0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
21100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21110 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
21120 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
21130 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
21140 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
21150 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
21160 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
21170 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
21180 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21190 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
211a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
211b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
211c0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
211d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
211e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
211f0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
21200 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
21210 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
21220 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
21230 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
21240 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
21250 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
21260 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
21270 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
21280 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
21290 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
212a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
212b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
212c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
212d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
212e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
212f0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
21300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
21310 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
21320 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
21330 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
21340 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
21350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21360 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
21370 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
21380 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
21390 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
213a0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
213b0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
213c0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
213d0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
213e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
213f0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
21400 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
21410 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
21420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21430 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
21440 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
21450 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
21460 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
21470 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
21480 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
21490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
214a0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
214b0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
214c0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
214d0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
214e0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
214f0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
21500 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
21510 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
21520 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
21530 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
21540 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
21550 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
21560 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
21570 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
21580 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
21590 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
215a0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
215b0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
215c0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
215d0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
215e0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
215f0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
21600 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
21610 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
21620 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
21630 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
21640 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
21650 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
21660 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
21670 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
21680 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
21690 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
216a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
216b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
216c0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
216d0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
216e0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
216f0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
21700 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
21710 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
21720 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
21730 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
21740 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
21750 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
21760 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
21770 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
21780 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
21790 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
217a0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
217b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
217c0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
217d0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
217e0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
217f0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
21800 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
21810 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
21820 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
21830 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
21840 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
21850 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
21860 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
21870 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
21880 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21890 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
218a0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
218b0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
218c0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
218d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
218e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
218f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21900 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
21910 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
21920 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
21930 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
21940 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
21950 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
21960 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
21970 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
21980 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
21990 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
219a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
219b0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
219c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
219d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
219e0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
219f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21a00 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
21a10 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
21a20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
21a30 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
21a40 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
21a50 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
21a60 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
21a70 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
21a80 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
21a90 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
21aa0 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
21ab0 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
21ac0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
21ad0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
21ae0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
21af0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
21b00 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
21b10 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
21b20 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
21b30 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
21b40 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
21b50 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
21b60 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
21b70 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
21b80 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
21b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21ba0 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
21bb0 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
21bc0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
21bd0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
21be0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
21bf0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
21c00 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
21c10 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
21c20 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
21c30 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
21c40 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
21c50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
21c60 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
21c70 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
21c80 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
21c90 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
21ca0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
21cb0 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
21cc0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
21cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
21ce0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
21cf0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
21d00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
21d10 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
21d20 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
21d30 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
21d40 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
21d50 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
21d60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
21d70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
21d80 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
21d90 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
21da0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
21db0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
21dc0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
21dd0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
21de0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
21df0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
21e00 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
21e10 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
21e20 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
21e30 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
21e40 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
21e50 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
21e60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21e70 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
21e80 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
21e90 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
21ea0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
21eb0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
21ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
21ee0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
21ef0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21f00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21f10 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
21f20 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
21f30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
21f40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21f50 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
21f60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21f70 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
21f80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21f90 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
21fa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21fb0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
21fc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
21fd0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
21fe0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21ff0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
22000 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
22010 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
22020 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
22030 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
22040 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
22050 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
22060 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
22070 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
22080 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22090 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
220a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
220b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
220c0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
220d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
220e0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
220f0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
22100 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
22110 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
22120 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
22130 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
22140 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
22150 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
22160 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
22170 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
22180 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
22190 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
221a0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
221b0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
221c0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
221d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
221e0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
221f0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
22200 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
22210 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
22220 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
22230 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
22240 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
22250 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
22260 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
22270 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
22280 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
22290 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
222a0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
222b0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
222c0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
222d0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
222e0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
222f0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
22300 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
22310 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
22320 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
22330 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
22340 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
22350 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
22360 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
22370 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
22380 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
22390 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
223a0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
223b0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
223c0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
223d0 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
223e0 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
223f0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
22400 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
22410 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
22420 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
22430 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
22440 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
22450 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
22460 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
22470 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
22480 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
22490 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
224a0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
224b0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
224c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
224d0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
224e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
224f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
22500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
22510 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
22520 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
22530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
22540 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
22550 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
22560 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
22570 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
22580 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
22590 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
225a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
225b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
225c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
225d0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
225e0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
225f0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
22600 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
22610 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
22620 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
22630 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
22640 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
22650 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
22660 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
22670 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
22680 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
22690 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
226a0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
226b0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
226c0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
226d0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
226e0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
226f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
22700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22710 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
22720 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22730 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
22740 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
22750 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
22760 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
22770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22780 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
22790 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
227a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
227b0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
227c0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
227d0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
227e0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
227f0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
22800 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
22810 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
22820 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
22830 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
22840 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
22850 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
22860 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
22870 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
22880 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
22890 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
228a0 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
228b0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
228c0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
228d0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
228e0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
228f0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
22900 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
22910 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
22920 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
22930 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
22940 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
22950 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
22960 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
22970 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
22980 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
22990 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
229a0 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
229b0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
229c0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
229d0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
229e0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
229f0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
22a00 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
22a10 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
22a20 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
22a30 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
22a40 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
22a50 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
22a60 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
22a70 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
22a80 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
22a90 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
22aa0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
22ab0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
22ac0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
22ad0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
22ae0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
22af0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
22b00 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
22b10 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
22b20 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
22b30 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
22b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
22b50 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
22b60 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
22b70 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
22b80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
22b90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
22ba0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
22bb0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
22bc0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
22bd0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
22be0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
22bf0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
22c00 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
22c10 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
22c20 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
22c30 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
22c40 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
22c50 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
22c60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
22c70 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
22c80 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
22c90 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
22ca0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
22cb0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
22cc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
22cd0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
22ce0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
22cf0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
22d00 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
22d10 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
22d20 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
22d30 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
22d40 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
22d50 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
22d60 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
22d70 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
22d80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
22d90 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
22da0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
22db0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
22dc0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
22dd0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
22de0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
22df0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
22e00 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
22e10 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
22e20 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
22e30 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
22e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22e50 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
22e60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22e70 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
22e80 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
22e90 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
22ea0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
22eb0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
22ec0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
22ed0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
22ee0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
22ef0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
22f00 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
22f10 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
22f20 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
22f30 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
22f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22f50 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
22f60 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
22f70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
22f80 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
22f90 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
22fa0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
22fb0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
22fc0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
22fd0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
22fe0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
22ff0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
23000 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23010 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
23020 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
23030 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
23040 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
23050 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
23060 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
23070 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
23080 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
23090 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72  6.23.1, it was r
230a0 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72  equired.** after
230b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
230c0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
230d0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
230e0 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a  LITE_ROW] that.*
230f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
23100 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ()] be called be
23110 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
23120 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
23130 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
23140 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
23150 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
23160 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69  _reset()] in thi
23170 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72  s way would.** r
23180 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
23190 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
231a0 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rn from sqlite3_
231b0 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
231c0 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  er.** version 3.
231d0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
231e0 73 74 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c  step() began cal
231f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
23200 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d  set()] .** autom
23210 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
23220 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
23230 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
23240 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
23250 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e  SE].  .**.** <b>
23260 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
23270 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
23280 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
23290 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
232a0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
232b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
232c0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
232d0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
232e0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
232f0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
23300 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
23310 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
23320 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
23330 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
23340 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
23350 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23360 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
23370 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
23380 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
23390 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
233a0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
233b0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
233c0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
233d0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
233e0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
233f0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
23400 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
23410 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
23420 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
23430 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
23440 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
23450 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
23460 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
23470 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23480 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
23490 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
234a0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
234b0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
234c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
234d0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
234e0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
234f0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
23500 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
23510 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
23520 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
23530 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
23540 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
23550 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
23560 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
23570 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
23580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23590 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
235a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
235b0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
235c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
235d0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
235e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
235f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23600 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
23610 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
23620 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
23630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23640 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
23650 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
23660 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
23670 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
23680 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
23690 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
236a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
236b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
236c0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
236d0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
236e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
236f0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
23700 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
23710 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
23720 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
23730 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
23740 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  pointer..**.** S
23750 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
23760 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
23770 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
23780 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
23790 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
237a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
237b0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
237c0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
237d0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
237e0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
237f0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
23800 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
23810 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
23820 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
23830 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
23840 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
23850 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
23860 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
23870 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
23880 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
23890 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
238a0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
238b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
238c0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
238d0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
238e0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
238f0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
23900 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
23910 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
23920 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
23930 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
23940 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
23950 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
23960 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
23970 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
23980 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
23990 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
239a0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
239b0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
239c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
239d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
239e0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
239f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
23a00 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
23a10 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
23a20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
23a30 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
23a40 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
23a50 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
23a60 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
23a70 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
23a80 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
23a90 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
23aa0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
23ab0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
23ac0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
23ad0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
23ae0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
23af0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
23b00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
23b10 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
23b20 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
23b30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
23b40 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
23b50 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
23b60 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
23b70 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
23b80 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
23b90 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
23ba0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
23bb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23bc0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
23bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23be0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
23bf0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
23c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
23c10 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
23c20 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
23c30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23c40 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
23c50 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
23c60 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
23c70 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
23c80 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
23c90 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
23ca0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
23cb0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
23cc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
23cd0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
23ce0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
23cf0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
23d00 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
23d10 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
23d20 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
23d30 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
23d40 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
23d50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
23d60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
23d70 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
23d80 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
23d90 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
23da0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
23db0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
23dc0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
23dd0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
23de0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
23df0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
23e00 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
23e10 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
23e20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23e30 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
23e40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
23e50 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
23e60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
23e70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23e80 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
23e90 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
23ea0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
23eb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23ec0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
23ed0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23ee0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23ef0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
23f00 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
23f10 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
23f20 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
23f30 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
23f40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
23f50 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
23f60 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
23f70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
23f80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23f90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
23fa0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
23fb0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
23fc0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
23fd0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
23fe0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
23ff0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
24000 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
24010 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
24020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24030 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
24040 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
24050 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
24060 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
24070 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
24080 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
24090 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
240a0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
240b0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
240c0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
240d0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
240e0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
240f0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
24100 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
24110 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
24120 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
24130 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
24140 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
24150 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
24160 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
24170 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
24180 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
24190 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
241a0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
241b0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
241c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
241d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
241e0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
241f0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
24200 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
24210 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
24220 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
24230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
24240 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
24250 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24260 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
24270 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
24280 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
24290 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
242a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
242b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
242c0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
242d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
242e0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
242f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
24300 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
24310 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
24320 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24330 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
24340 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
24350 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
24360 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
24370 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
24380 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
24390 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
243a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
243b0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
243c0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
243d0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
243e0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
243f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
24400 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
24410 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24420 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
24430 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
24440 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
24450 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
24460 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
24470 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
24480 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
24490 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
244a0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
244b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
244c0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
244d0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
244e0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
244f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
24500 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
24510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24520 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
24530 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
24540 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
24550 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
24560 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
24570 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
24580 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
24590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
245a0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
245b0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
245c0 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
245d0 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
245e0 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
245f0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
24600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24610 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
24620 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
24630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24640 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
24650 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
24660 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
24670 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
24680 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
24690 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65  .** ^The zero te
246a0 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
246b0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
246c0 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54   count..**.** ^T
246d0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
246e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
246f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
24700 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
24710 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24720 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
24730 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24740 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
24750 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
24760 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
24770 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
24780 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
24790 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
247a0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
247b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
247c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
247d0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
247e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
247f0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
24800 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
24810 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
24820 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
24830 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
24840 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
24850 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
24860 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
24870 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
24880 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24890 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
248a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
248b0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
248c0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
248d0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
248e0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
248f0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
24900 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
24910 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
24920 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
24930 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
24940 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
24950 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
24960 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
24970 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
24980 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
24990 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
249a0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
249b0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
249c0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
249d0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
249e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
249f0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
24a00 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
24a10 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
24a20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
24a30 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
24a40 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
24a50 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
24a60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
24a70 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
24a80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
24a90 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
24aa0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
24ab0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
24ac0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24ad0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
24ae0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
24af0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
24b00 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24b10 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
24b20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
24b30 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
24b40 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
24b50 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
24b60 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
24b70 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
24b80 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
24b90 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
24ba0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
24bb0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
24bc0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
24bd0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
24be0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
24bf0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
24c00 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
24c10 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
24c20 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
24c30 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
24c40 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
24c50 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
24c60 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
24c70 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
24c80 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
24c90 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
24ca0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
24cb0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
24cc0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
24cd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
24ce0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
24cf0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
24d00 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24d10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
24d20 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
24d30 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
24d40 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
24d50 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
24d60 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
24d70 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
24d80 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
24d90 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
24da0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
24db0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24dc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
24dd0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
24de0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
24df0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
24e00 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
24e10 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
24e20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
24e30 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
24e40 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
24e50 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
24e60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
24e70 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
24e80 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
24e90 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
24ea0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
24eb0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
24ec0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
24ed0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
24ee0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
24ef0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
24f00 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
24f10 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
24f20 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
24f30 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
24f40 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
24f50 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
24f60 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
24f70 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
24f80 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
24f90 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  ammers..**.** ^N
24fa0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
24fb0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
24fc0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
24fd0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
24fe0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
24ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
25000 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
25010 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
25020 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
25030 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
25040 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
25050 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65  .** ^(Type conve
25060 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
25070 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
25080 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
25090 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
250a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
250b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
250c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
250d0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
250e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
250f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
25100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25110 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
25120 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
25130 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
25140 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
25150 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
25160 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
25170 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
25180 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
25190 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
251a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
251b0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
251c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
251d0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
251e0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
251f0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
25200 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
25210 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
25220 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
25230 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
25240 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25250 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
25260 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
25270 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
25280 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
25290 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
252a0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
252b0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
252c0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ul>)^.**.** ^Con
252d0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
252e0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
252f0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
25300 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
25310 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
25320 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
25330 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
25340 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
25350 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
25360 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
25370 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
25380 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
25390 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
253a0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
253b0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
253c0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
253d0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
253e0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
253f0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
25400 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
25410 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
25420 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
25430 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
25440 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66  .**.** ^(The saf
25450 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
25460 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
25470 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
25480 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
25490 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
254a0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
254b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
254c0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
254d0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
254e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
254f0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
25500 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
25510 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
25520 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
25530 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
25540 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
25550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
25560 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
25570 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
25580 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
25590 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
255a0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
255b0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
255c0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
255d0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
255e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
255f0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
25600 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
25610 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
25620 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
25630 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
25640 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
25650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25660 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
25670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25680 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
25690 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
256a0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
256b0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
256c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
256d0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
256e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
256f0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
25700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25710 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
25720 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
25730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25740 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
25750 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
25760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
25770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
25780 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
25790 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
257a0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
257b0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
257c0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
257d0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
257e0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
257f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
25800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
25810 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
25820 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
25830 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
25840 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
25850 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
25860 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
25870 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
25880 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
25890 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
258a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
258b0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
258c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
258d0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
258e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
258f0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
25900 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
25910 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
25920 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
25930 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
25940 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
25950 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
25960 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
25970 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
25980 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
25990 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
259a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
259b0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
259c0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
259d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
259e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
259f0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
25a00 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
25a10 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
25a20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25a30 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
25a40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25a50 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
25a60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
25a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25a80 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
25a90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25aa0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25ab0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
25ac0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
25ad0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
25ae0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25af0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
25b00 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
25b10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25b20 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
25b30 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
25b40 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
25b50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25b60 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
25b70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
25b80 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
25b90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25ba0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
25bb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25bc0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
25bd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
25bf0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
25c00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25c10 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
25c20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25c30 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
25c40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25c50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25c60 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
25c70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
25c80 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
25c90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
25ca0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
25cb0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
25cc0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25cd0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
25ce0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
25cf0 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  s executed succe
25d00 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65  ssfully or not e
25d10 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
25d20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  then.** SQLITE_O
25d30 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e  K is returned. ^
25d40 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
25d50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
25d60 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
25d70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
25d80 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
25d90 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
25da0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
25db0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
25dc0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
25dd0 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
25de0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
25df0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25e00 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20  ment].  ^If the 
25e10 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
25e20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
25e30 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
25e40 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
25e50 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
25e60 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
25e70 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
25e80 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
25e90 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
25ea0 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63  errupt]..** ^Inc
25eb0 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
25ec0 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
25ed0 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
25ee0 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
25ef0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
25f00 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
25f10 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
25f20 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
25f30 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
25f40 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74  E_ABORT]..*/.int
25f50 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
25f60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
25f70 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25f80 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
25f90 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25fa0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
25fb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
25fc0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
25fd0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
25fe0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25ff0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
26000 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
26010 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
26020 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
26030 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
26040 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
26050 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
26060 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
26070 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
26080 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
26090 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
260a0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
260b0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
260c0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
260d0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
260e0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
260f0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
26100 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
26110 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
26120 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
26130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26140 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
26150 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
26160 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
26170 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
26180 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
26190 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
261a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
261b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
261c0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
261d0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
261e0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
261f0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
26200 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
26210 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
26220 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
26230 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26240 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
26250 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
26260 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
26270 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
26280 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
26290 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
262a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
262b0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
262c0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
262d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
262e0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
262f0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
26300 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
26310 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
26320 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
26330 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
26340 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
26350 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
26360 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
26370 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26380 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
26390 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
263a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
263b0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
263c0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
263d0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
263e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
263f0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
26400 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
26410 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
26420 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
26430 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
26440 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
26450 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
26460 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
26470 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
26480 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
26490 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
264a0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
264b0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
264c0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
264d0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
264e0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
264f0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
26500 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
26510 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
26520 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
26530 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
26540 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
26550 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
26560 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
26570 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
26580 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26590 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
265a0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
265b0 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
265c0 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
265d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
265e0 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
265f0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
26600 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26610 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  6()..**.** ^The 
26620 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26630 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
26640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
26650 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
26660 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
26670 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
26680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
26690 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
266a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
266b0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
266c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
266d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
266e0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
266f0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
26700 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
26710 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
26720 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
26730 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
26740 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
26750 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
26760 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
26770 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
26780 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
26790 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
267a0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
267b0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
267c0 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
267d0 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
267e0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
267f0 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
26800 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20  aracters.  ^Any 
26810 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
26820 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
26830 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
26840 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
26850 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
26860 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
26870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
26880 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
26890 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
268a0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
268b0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
268c0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
268d0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
268e0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
268f0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
26900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
26910 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
26920 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
26930 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
26940 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
26950 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
26960 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
26970 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
26980 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
26990 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
269a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
269b0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
269c0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
269d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
269e0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
269f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
26a00 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
26a10 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
26a20 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
26a30 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
26a40 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
26a50 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
26a60 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
26a70 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
26a80 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
26a90 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
26aa0 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
26ab0 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
26ac0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
26ad0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
26ae0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
26af0 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
26b00 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
26b10 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
26b20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
26b30 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
26b40 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
26b50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26b60 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
26b70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26b80 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
26b90 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
26ba0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
26bb0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
26bc0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
26bd0 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
26be0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
26bf0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
26c00 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
26c10 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
26c20 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
26c30 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
26c40 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
26c50 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
26c60 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
26c70 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
26c80 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
26c90 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
26ca0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
26cb0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
26cc0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
26cd0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
26ce0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
26cf0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
26d00 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
26d10 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
26d20 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
26d30 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
26d40 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
26d50 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
26d60 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
26d70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
26d80 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
26d90 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].)^.**.** The 
26da0 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
26db0 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
26dc0 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
26dd0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
26de0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
26df0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
26e00 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
26e10 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
26e20 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
26e30 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
26e40 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
26e50 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
26e60 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
26e70 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
26e80 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
26e90 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
26ea0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
26eb0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
26ec0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
26ed0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
26ee0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
26ef0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
26f00 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
26f10 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
26f20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
26f30 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
26f40 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
26f50 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
26f60 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
26f70 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
26f80 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
26f90 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
26fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
26fb0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
26fc0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
26fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
26fe0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
26ff0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
27000 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
27010 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
27020 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
27030 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
27040 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
27050 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
27060 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
27070 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
27080 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
27090 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
270a0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
270b0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
270c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
270d0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
270e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
270f0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
27100 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
27110 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
27120 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
27130 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
27140 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
27150 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
27160 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
27170 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
27180 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
27190 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
271a0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
271b0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
271c0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
271d0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
271e0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
271f0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
27200 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
27210 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
27220 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
27230 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
27240 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
27250 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
27260 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
27270 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
27280 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
27290 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
272a0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
272b0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
272c0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
272d0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
272e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
272f0 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ions..** ^The fi
27300 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
27310 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27320 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
27330 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
27340 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
27350 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
27360 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
27370 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
27380 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
27390 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c  ^Subsequent appl
273a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
273b0 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  functions of the
273c0 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20   same name only 
273d0 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69  override .** pri
273e0 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  or application-d
273f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
27400 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61   that are an exa
27410 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65  ct match for the
27420 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  .** number of pa
27430 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65  rameters and pre
27440 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e  ferred encoding.
27450 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
27460 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27470 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
27480 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
27490 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
274a0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
274b0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
274c0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
274d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
274e0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
274f0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
27500 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
27510 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
27520 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
27530 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
27540 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27550 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
27560 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
27570 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
27580 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
27590 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
275a0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
275b0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
275c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
275d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
275e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
275f0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
27600 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
27610 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
27620 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
27630 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
27640 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27650 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
27660 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
27670 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
27680 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
27690 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
276a0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
276b0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
276c0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
276d0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
276e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
276f0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
27700 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27710 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
27720 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
27730 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
27740 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
27750 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27760 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
27770 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
27780 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
27790 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
277a0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
277b0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
277c0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
277d0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
277e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
277f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
27800 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
27810 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
27820 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
27830 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
27840 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
27850 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
27860 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
27870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27880 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
27890 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
278a0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
278b0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
278c0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
278d0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
278e0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
278f0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
27900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27910 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
27920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27930 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
27940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27950 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
27960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27970 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
27980 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
27990 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
279a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
279b0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
279c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
279d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
279e0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
279f0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
27a00 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
27a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27a20 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
27a30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
27a40 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
27a50 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
27a60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
27a70 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
27a80 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
27a90 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
27aa0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
27ab0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
27ac0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
27ad0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
27ae0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
27af0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
27b00 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
27b10 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
27b20 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
27b30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
27b40 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
27b50 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
27b60 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
27b70 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
27b80 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
27b90 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
27ba0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
27bb0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
27bc0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
27bd0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
27be0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27bf0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
27c00 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
27c10 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
27c20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
27c30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27c40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
27c50 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
27c60 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
27c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
27c80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
27c90 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
27ca0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
27cb0 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
27cc0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
27cd0 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
27ce0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
27cf0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
27d00 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
27d10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
27d20 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
27d30 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
27d40 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
27d50 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
27d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27d70 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
27d80 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
27d90 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
27da0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
27db0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
27dc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
27dd0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
27de0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
27df0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
27e00 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
27e10 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
27e20 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
27e30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
27e40 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
27e50 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
27e60 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
27e70 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
27e80 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
27e90 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
27ea0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
27eb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27ec0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
27ed0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
27ee0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
27ef0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
27f00 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
27f10 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
27f20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
27f30 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
27f40 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
27f50 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
27f60 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
27f70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27f80 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
27f90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27fa0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
27fb0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
27fc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27fd0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
27fe0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
27ff0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
28000 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
28010 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28020 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
28030 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
28040 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
28050 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28060 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
28070 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
28080 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
28090 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
280a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
280b0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
280c0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
280d0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
280e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
280f0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
28100 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
28110 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
28120 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
28130 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
28140 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
28150 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
28160 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28170 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
28180 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
28190 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
281a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
281b0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
281c0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
281d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
281e0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
281f0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
28200 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
28210 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
28220 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
28230 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
28240 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
28250 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
28260 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
28270 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
28280 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
28290 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
282a0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
282b0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
282c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
282d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
282e0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
282f0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
28300 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
28310 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
28320 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
28330 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
28340 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
28350 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
28360 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
28370 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
28380 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
28390 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
283a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
283b0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
283c0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
283d0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
283e0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
283f0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
28400 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
28410 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
28420 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
28430 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
28440 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
28450 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
28460 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
28470 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
28480 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
28490 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
284a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
284b0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
284c0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
284d0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
284e0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
284f0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
28500 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
28510 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28520 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
28530 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28540 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
28550 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
28560 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
28570 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
28580 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
28590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
285a0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
285b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
285c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
285d0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
285e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
285f0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
28600 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
28610 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
28620 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
28630 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
28640 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28650 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
28660 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
28670 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
28680 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
28690 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
286a0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
286b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
286c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
286d0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
286e0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
286f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
28700 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
28710 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
28720 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
28730 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
28740 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
28750 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
28760 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28770 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
28780 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
28790 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
287a0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
287b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
287c0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
287d0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
287e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
287f0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
28800 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
28810 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28820 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
28830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28840 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
28850 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
28860 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28870 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
28880 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
28890 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
288a0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
288b0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
288c0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
288d0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
288e0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
288f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
28900 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
28910 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
28920 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
28930 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
28940 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
28950 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
28960 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28970 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
28980 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
28990 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
289a0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
289b0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
289c0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
289d0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
289e0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
289f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
28a00 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
28a10 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
28a20 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
28a30 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
28a40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
28a50 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
28a60 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
28a70 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
28a80 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
28a90 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
28aa0 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
28ab0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
28ac0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
28ad0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
28ae0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
28af0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
28b00 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
28b10 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
28b20 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
28b30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
28b40 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
28b50 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
28b60 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
28b70 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
28b80 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
28b90 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
28ba0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
28bb0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
28bc0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
28bd0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
28be0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
28bf0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
28c00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
28c10 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
28c20 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
28c30 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
28c40 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
28c50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
28c60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28c70 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
28c80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
28c90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e  ULL pointer if N
28ca0 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
28cb0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
28cc0 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
28cd0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
28ce0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
28cf0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
28d00 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
28d10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
28d20 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
28d30 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
28d40 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
28d50 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
28d60 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
28d70 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
28d80 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
28d90 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
28da0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28db0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
28dc0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
28dd0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
28de0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
28df0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
28e00 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
28e10 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ion.)^.**.** ^SQ
28e20 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
28e30 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
28e40 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
28e50 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
28e60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
28e70 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
28e80 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
28e90 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
28ea0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
28eb0 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
28ec0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
28ed0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
28ee0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
28ef0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
28f00 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
28f10 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
28f20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
28f30 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
28f40 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
28f50 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
28f60 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
28f70 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
28f80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
28f90 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
28fa0 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
28fb0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
28fc0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
28fd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
28fe0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28ff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29000 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
29010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29020 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
29030 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
29040 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
29050 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
29060 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
29070 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
29080 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
29090 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
290a0 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
290b0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
290c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
290d0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
290e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
290f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
29100 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
29110 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
29120 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
29130 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
29140 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
29150 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
29160 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
29170 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
29180 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
29190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
291a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
291b0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
291c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
291d0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
291e0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
291f0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
29200 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
29210 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
29220 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
29230 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
29240 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
29250 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
29260 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
29270 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
29280 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
29290 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
292a0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
292b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
292c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
292d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
292e0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
292f0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
29300 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
29310 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29320 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
29330 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
29340 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
29350 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
29360 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
29370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
29380 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
29390 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
293a0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
293b0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
293c0 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
293d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
293e0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
293f0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
29400 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
29410 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
29420 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
29430 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
29440 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
29450 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
29460 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
29470 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
29480 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
29490 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
294a0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
294b0 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
294c0 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
294d0 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
294e0 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
294f0 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
29500 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
29510 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
29520 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
29530 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
29540 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
29550 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
29560 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
29570 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
29580 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
29590 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
295a0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
295b0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
295c0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
295d0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
295e0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
295f0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
29600 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
29610 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
29620 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
29630 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
29640 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
29650 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
29660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29670 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
29680 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29690 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
296a0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
296b0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
296c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
296d0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
296e0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
296f0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
29700 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
29710 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29720 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64  on. ^If no metad
29730 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
29740 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
29750 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
29760 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
29770 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
29780 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
29790 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
297a0 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
297b0 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
297c0 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
297d0 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
297e0 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
297f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
29800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29810 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
29820 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
29830 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
29840 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
29850 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
29860 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
29870 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
29880 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
29890 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
298a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
298b0 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
298c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
298d0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
298e0 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
298f0 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
29900 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
29910 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74  royed..** ^If it
29920 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
29930 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
29940 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
29950 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
29960 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
29970 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29980 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
29990 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
299a0 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
299b0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
299c0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
299d0 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
299e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
299f0 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
29a00 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
29a10 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
29a20 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
29a30 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
29a40 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
29a50 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
29a60 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
29a70 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
29a80 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75  e.  ^The only gu
29a90 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
29aa0 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
29ab0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
29ac0 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
29ad0 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
29ae0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
29af0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
29b00 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
29b10 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
29b20 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
29b30 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
29b40 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
29b50 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
29b60 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
29b70 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
29b80 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a  rameters].)^.**.
29b90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
29ba0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
29bb0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
29bc0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
29bd0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
29be0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
29bf0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
29c00 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
29c10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29c20 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
29c30 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
29c40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29c50 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
29c60 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
29c70 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
29c80 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
29c90 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
29ca0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
29cb0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
29cc0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
29cd0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
29ce0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
29cf0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
29d00 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
29d10 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
29d20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
29d30 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
29d40 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
29d50 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
29d60 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
29d70 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
29d80 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
29d90 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
29da0 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
29db0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
29dc0 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
29dd0 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
29de0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
29df0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
29e00 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
29e10 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
29e20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
29e30 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
29e40 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
29e50 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
29e60 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
29e70 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
29e80 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
29e90 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
29ea0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
29eb0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
29ec0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
29ed0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
29ee0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
29ef0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
29f00 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
29f10 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
29f20 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
29f30 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
29f40 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
29f50 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
29f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
29f70 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
29f80 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
29f90 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
29fa0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
29fb0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
29fc0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
29fd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
29fe0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
29ff0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
2a000 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
2a010 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
2a020 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2a030 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
2a040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2a050 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2a060 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2a070 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2a080 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
2a090 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2a0a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2a0b0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
2a0c0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
2a0d0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
2a0e0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
2a0f0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
2a100 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
2a110 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2a120 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
2a130 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
2a140 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
2a150 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
2a160 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
2a170 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2a180 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
2a190 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2a1a0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
2a1b0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2a1c0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2a1d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2a1e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2a1f0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
2a200 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
2a210 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
2a220 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
2a230 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
2a240 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
2a250 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
2a260 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
2a270 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a280 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
2a290 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
2a2a0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
2a2b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2a2c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2a2d0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
2a2e0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
2a2f0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
2a300 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
2a310 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
2a320 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
2a330 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
2a340 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a350 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
2a360 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2a370 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2a380 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a390 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2a3a0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
2a3b0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
2a3c0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
2a3d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2a3e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a3f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2a400 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2a410 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
2a420 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
2a430 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
2a440 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
2a450 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
2a460 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
2a470 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
2a480 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
2a490 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
2a4a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
2a4b0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
2a4c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a4d0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
2a4e0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
2a4f0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
2a500 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
2a510 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2a520 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
2a530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a540 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
2a550 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
2a560 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
2a570 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
2a580 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2a590 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
2a5a0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
2a5b0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
2a5c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2a5d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a5e0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
2a5f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a600 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
2a610 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2a620 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
2a630 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
2a640 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
2a650 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2a660 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
2a670 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2a680 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2a690 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2a6a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2a6b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2a6c0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
2a6d0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
2a6e0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
2a6f0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2a700 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
2a710 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2a720 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2a730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a740 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2a750 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2a760 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
2a770 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
2a780 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2a790 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2a7a0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
2a7b0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
2a7c0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
2a7d0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
2a7e0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
2a7f0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
2a800 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
2a810 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2a820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2a830 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2a840 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
2a850 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
2a860 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
2a870 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
2a880 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
2a890 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
2a8a0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
2a8b0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
2a8c0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
2a8d0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
2a8e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2a8f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
2a900 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2a910 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
2a920 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
2a930 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
2a940 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
2a950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a960 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
2a970 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
2a980 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
2a990 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
2a9a0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
2a9b0 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
2a9c0 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
2a9d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a9e0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
2a9f0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
2aa00 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2aa10 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
2aa20 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
2aa30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2aa40 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
2aa50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2aa60 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
2aa70 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2aa80 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2aa90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2aaa0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2aab0 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
2aac0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2aad0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2aae0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2aaf0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
2ab00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2ab10 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
2ab20 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2ab30 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2ab40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ab50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ab60 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
2ab70 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2ab80 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2ab90 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2aba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2abb0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
2abc0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2abd0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2abe0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2abf0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ac00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
2ac10 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2ac20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ac30 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
2ac40 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
2ac50 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2ac60 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
2ac70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ac80 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
2ac90 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
2aca0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2acb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2acc0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2acd0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
2ace0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
2acf0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
2ad00 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
2ad10 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ad20 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
2ad30 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
2ad40 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
2ad50 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2ad60 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
2ad70 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
2ad80 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
2ad90 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
2ada0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2adb0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
2adc0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2add0 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
2ade0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2adf0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2ae00 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2ae10 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
2ae20 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
2ae30 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
2ae40 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
2ae50 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
2ae60 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2ae70 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
2ae80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
2ae90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2aea0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2aeb0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2aec0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
2aed0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
2aee0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
2aef0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
2af00 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
2af10 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
2af20 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
2af30 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
2af40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
2af50 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
2af60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2af70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2af80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2af90 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2afa0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2afb0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
2afc0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
2afd0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
2afe0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
2aff0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
2b000 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
2b010 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
2b020 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
2b030 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
2b040 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
2b050 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2b060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2b070 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b080 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
2b090 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
2b0a0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2b0b0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2b0c0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
2b0d0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
2b0e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2b0f0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
2b100 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
2b110 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
2b120 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
2b130 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2b140 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
2b150 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
2b160 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
2b170 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
2b180 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2b190 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
2b1a0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2b1b0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2b1c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2b1d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
2b1e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2b1f0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
2b200 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
2b210 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
2b220 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
2b230 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2b240 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
2b250 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
2b260 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
2b270 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
2b280 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
2b290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b2a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2b2b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2b2c0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2b2d0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2b2e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2b2f0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
2b300 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
2b310 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b320 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
2b330 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
2b340 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
2b350 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2b360 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2b370 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
2b380 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2b390 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
2b3a0 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
2b3b0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
2b3c0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2b3d0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
2b3e0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
2b3f0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2b400 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
2b410 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
2b420 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
2b430 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b440 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
2b450 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
2b460 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
2b470 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b480 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
2b490 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
2b4a0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
2b4b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2b4c0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
2b4d0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
2b4e0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
2b4f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2b500 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2b510 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
2b520 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
2b530 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
2b540 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
2b550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b560 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
2b570 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
2b580 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
2b590 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
2b5a0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2b5b0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
2b5c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
2b5d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b5e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2b5f0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2b600 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2b610 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
2b620 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b630 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
2b640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b650 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
2b660 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2b670 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2b680 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b690 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
2b6a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2b6b0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
2b6c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b6d0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
2b6e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2b6f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b700 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
2b710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2b720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b730 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2b740 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b750 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2b760 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2b770 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b780 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2b790 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
2b7a0 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
2b7b0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
2b7c0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
2b7d0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
2b7e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2b7f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b800 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
2b810 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2b820 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
2b830 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2b840 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b850 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
2b860 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2b870 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2b880 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2b890 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b8a0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
2b8b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2b8c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2b8d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2b8e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b8f0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
2b900 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2b910 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
2b920 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b930 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b940 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
2b950 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2b960 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
2b970 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b980 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2b990 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2b9a0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2b9b0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
2b9c0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
2b9d0 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ces.**.** These 
2b9e0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
2b9f0 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
2ba00 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2ba10 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
2ba20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ba30 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
2ba40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ba50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
2ba60 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
2ba70 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2ba80 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
2ba90 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
2baa0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2bab0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2bac0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
2bad0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2bae0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
2baf0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
2bb00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2bb10 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e  llation16(). ^In
2bb20 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
2bb30 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
2bb40 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
2bb50 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2bb60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2bb70 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
2bb80 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
2bb90 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
2bba0 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
2bbb0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b  E_UTF16LE], or [
2bbc0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2bbd0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2bbe0 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
2bbf0 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
2bc00 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
2bc10 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
2bc20 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
2bc30 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
2bc40 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2bc50 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2bc60 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig-endian, respe
2bc70 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a  ctively. ^The.**
2bc80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2bc90 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53  might also be [S
2bca0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20  QLITE_UTF16] to 
2bcb0 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68  indicate that th
2bcc0 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70  e routine.** exp
2bcd0 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
2bce0 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e   be UTF-16 strin
2bcf0 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  gs in the native
2bd00 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20   byte order, or 
2bd10 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
2bd20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  can be [SQLITE_U
2bd30 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66  TF16_ALIGNED] if
2bd40 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74   the.** the rout
2bd50 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e  ine expects poin
2bd60 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77  ters to 16-bit w
2bd70 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69  ord aligned stri
2bd80 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36  ngs.** of UTF-16
2bd90 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
2bda0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
2bdb0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
2bdc0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
2bdd0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2bde0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2bdf0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
2be00 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c    ^If it is NULL
2be10 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
2be20 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
2be30 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
2be40 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
2be50 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
2be60 63 61 6c 6c 20 69 74 20 61 6e 79 20 6d 6f 72 65  call it any more
2be70 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d 65  )..** ^Each time
2be80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2be90 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69   supplied functi
2bea0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  on is invoked, i
2beb0 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61  t is passed.** a
2bec0 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61  s its first para
2bed0 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20  meter a copy of 
2bee0 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64  the void* passed
2bef0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
2bf00 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2bf10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bf20 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  lation() or sqli
2bf30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2bf40 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20  tion16()..**.** 
2bf50 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61  ^The remaining a
2bf60 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2bf70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
2bf80 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
2bf90 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
2bfa0 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
2bfb0 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
2bfc0 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
2bfd0 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
2bfe0 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
2bff0 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
2c000 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2c010 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
2c020 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
2c030 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 20  ** registered.  
2c040 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2c050 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2c060 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  n routine should
2c070 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74  .** return negat
2c080 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
2c090 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72  itive if the fir
2c0a0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
2c0b0 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c  s than,.** equal
2c0c0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
2c0d0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20  than the second 
2c0e0 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
2c0f0 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
2c100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c110 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2c120 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
2c130 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
2c140 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2c150 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2c160 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
2c170 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
2c180 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
2c190 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
2c1a0 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65 73  ation.  ^The des
2c1b0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2c1c0 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
2c1d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
2c1e0 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
2c1f0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
2c200 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c210 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
2c220 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
2c230 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c240 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  on_v2()..** ^Col
2c250 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
2c260 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
2c270 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
2c280 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
2c290 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
2c2a0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
2c2b0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
2c2c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c2d0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
2c2e0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2c2f0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
2c300 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
2c310 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2c320 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
2c330 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2c340 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
2c350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2c360 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
2c370 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2c380 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2c390 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2c3a0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2c3b0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2c3c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2c3d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2c3e0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
2c3f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2c400 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2c410 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2c420 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2c430 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2c440 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2c450 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2c460 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2c470 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
2c480 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2c490 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
2c4a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c4b0 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
2c4c0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2c4d0 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
2c4e0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2c4f0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2c500 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2c510 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2c520 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2c530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c540 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
2c550 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
2c560 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
2c570 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
2c580 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
2c590 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
2c5a0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
2c5b0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
2c5c0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
2c5d0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
2c5e0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
2c5f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2c600 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
2c610 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2c620 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
2c630 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2c640 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
2c650 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
2c660 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
2c670 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
2c680 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2c690 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
2c6a0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
2c6b0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
2c6c0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
2c6d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2c6e0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
2c6f0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
2c700 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
2c710 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2c720 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
2c730 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
2c740 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
2c750 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
2c760 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
2c770 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
2c780 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
2c790 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
2c7a0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
2c7b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2c7c0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
2c7d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2c7e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2c7f0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2c800 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2c810 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2c820 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2c830 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2c840 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c850 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2c860 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2c870 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2c880 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2c890 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
2c8a0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2c8b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2c8c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2c8d0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2c8e0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
2c8f0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
2c900 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2c910 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2c920 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
2c930 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
2c940 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c950 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2c960 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
2c970 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2c980 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
2c990 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2c9a0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
2c9b0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
2c9c0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
2c9d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2c9e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
2c9f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ca00 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
2ca10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2ca20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2ca30 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
2ca40 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2ca50 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2ca60 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2ca70 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2ca80 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2ca90 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2caa0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2cab0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2cac0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2cad0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2cae0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2caf0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2cb00 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2cb10 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
2cb20 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
2cb30 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2cb40 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2cb50 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2cb60 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2cb70 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2cb80 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2cb90 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2cba0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2cbb0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2cbc0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2cbd0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2cbe0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2cbf0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2cc00 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2cc10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2cc20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2cc30 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2cc40 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2cc50 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2cc60 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2cc70 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2cc80 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2cc90 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2cca0 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2ccb0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2ccc0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2ccd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2cce0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2ccf0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2cd00 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2cd10 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2cd20 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2cd30 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2cd40 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2cd50 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2cd60 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2cd70 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2cd80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2cd90 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2cda0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2cdb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2cdc0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2cdd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2cde0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2cdf0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2ce00 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2ce10 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2ce20 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2ce30 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
2ce40 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2ce50 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2ce60 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
2ce70 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2ce80 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2ce90 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
2cea0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2ceb0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2cec0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2ced0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
2cee0 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
2cef0 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
2cf00 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2cf10 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
2cf20 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
2cf30 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2cf40 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2cf50 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
2cf60 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2cf70 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2cf80 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2cf90 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2cfa0 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2cfb0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2cfc0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2cfd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2cfe0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2cff0 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2d000 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
2d010 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
2d020 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
2d030 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
2d040 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
2d050 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
2d060 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
2d070 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
2d080 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
2d090 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2d0a0 5e 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e  ^If the operatin
2d0b0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
2d0c0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
2d0d0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
2d0e0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
2d0f0 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
2d100 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
2d110 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
2d120 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
2d130 20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75   second. ^The nu
2d140 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2d150 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
2d160 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
2d170 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
2d180 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
2d190 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2d1a0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
2d1b0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
2d1c0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
2d1d0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
2d1e0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
2d1f0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
2d200 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74  ] object..*/.int
2d210 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
2d220 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2d230 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
2d240 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2d250 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2d260 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
2d270 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2d280 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2d290 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2d2a0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2d2b0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2d2c0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
2d2d0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
2d2e0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
2d2f0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
2d300 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
2d310 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
2d320 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
2d330 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2d340 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
2d350 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
2d360 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
2d370 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2d380 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
2d390 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2d3a0 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
2d3b0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
2d3c0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2d3d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2d3e0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2d3f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
2d400 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
2d410 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
2d420 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
2d430 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2d440 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2d450 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
2d460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d470 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
2d480 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2d490 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
2d4a0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
2d4b0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2d4c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2d4d0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2d4e0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2d4f0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2d500 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2d510 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2d520 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2d530 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
2d540 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2d550 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
2d560 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
2d570 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
2d580 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2d590 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
2d5a0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2d5b0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
2d5c0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
2d5d0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2d5e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d5f0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
2d600 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
2d610 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2d620 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
2d630 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
2d640 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
2d650 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2d660 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
2d670 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
2d680 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
2d690 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2d6a0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
2d6b0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
2d6c0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
2d6d0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2d6e0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
2d6f0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
2d700 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
2d710 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
2d720 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
2d730 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
2d740 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
2d750 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2d760 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2d770 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
2d780 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
2d790 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2d7a0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
2d7b0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2d7c0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
2d7d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
2d7e0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
2d7f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d800 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
2d810 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
2d820 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
2d830 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
2d840 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2d850 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
2d860 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
2d870 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
2d880 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
2d890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d8a0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
2d8b0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
2d8c0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
2d8d0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
2d8e0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
2d8f0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
2d900 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2d910 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2d920 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2d930 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2d940 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
2d950 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
2d960 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
2d970 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
2d980 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
2d990 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
2d9a0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
2d9b0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
2d9c0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
2d9d0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
2d9e0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
2d9f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
2da00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2da10 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2da20 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
2da30 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
2da40 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
2da50 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
2da60 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
2da70 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
2da80 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
2da90 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
2daa0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2dab0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
2dac0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
2dad0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
2dae0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
2daf0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
2db00 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
2db10 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
2db20 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
2db30 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2db40 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
2db50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
2db60 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
2db70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2db80 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2db90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2dba0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
2dbb0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
2dbc0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2dbd0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2dbe0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2dbf0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2dc00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2dc10 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
2dc20 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
2dc30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dc40 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
2dc50 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
2dc60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
2dc70 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
2dc80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2dc90 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
2dca0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
2dcb0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
2dcc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2dcd0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
2dce0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2dcf0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
2dd00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dd10 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
2dd20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
2dd30 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
2dd40 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
2dd50 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
2dd60 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
2dd70 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
2dd80 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
2dd90 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2dda0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
2ddb0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
2ddc0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
2ddd0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2dde0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ddf0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
2de00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2de10 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
2de20 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
2de30 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2de40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
2de50 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
2de60 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
2de70 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2de80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2de90 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
2dea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2deb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2dec0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2ded0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
2dee0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
2def0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
2df00 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
2df10 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
2df20 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
2df30 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
2df40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2df50 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
2df60 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
2df70 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2df80 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
2df90 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
2dfa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2dfb0 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
2dfc0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
2dfd0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
2dfe0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
2dff0 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
2e000 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
2e010 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
2e020 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2e030 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2e040 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
2e050 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2e060 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2e070 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2e080 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
2e090 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
2e0a0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
2e0b0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
2e0c0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
2e0d0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
2e0e0 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
2e0f0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2e100 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2e110 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2e120 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2e130 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2e140 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2e150 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2e160 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
2e170 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2e180 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2e190 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2e1a0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2e1b0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2e1c0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2e1d0 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2e1e0 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2e1f0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2e200 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2e210 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2e220 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2e230 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2e240 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2e250 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2e260 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
2e270 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
2e280 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2e290 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2e2a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
2e2b0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
2e2c0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
2e2d0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2e2e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
2e2f0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
2e300 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
2e310 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
2e320 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2e330 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
2e340 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2e350 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
2e360 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
2e370 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
2e380 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
2e390 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
2e3a0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
2e3b0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2e3c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
2e3d0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
2e3e0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
2e3f0 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
2e400 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
2e410 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
2e420 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
2e430 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
2e440 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
2e450 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
2e460 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
2e470 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
2e480 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
2e490 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2e4a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2e4b0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2e4c0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2e4d0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2e4e0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2e4f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2e500 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2e510 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
2e520 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
2e530 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2e540 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
2e550 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
2e560 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2e570 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
2e580 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
2e590 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
2e5a0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
2e5b0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
2e5c0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
2e5d0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
2e5e0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
2e5f0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2e600 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
2e610 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
2e620 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
2e630 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
2e640 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
2e650 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
2e660 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
2e670 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
2e680 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
2e690 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2e6a0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2e6b0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2e6c0 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2e6d0 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2e6e0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
2e6f0 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
2e700 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
2e710 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
2e720 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
2e730 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
2e740 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
2e750 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
2e760 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
2e770 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
2e780 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
2e790 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
2e7a0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
2e7b0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
2e7c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
2e7d0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
2e7e0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
2e7f0 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
2e800 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
2e810 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
2e820 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
2e830 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
2e840 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
2e850 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2e860 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2e870 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2e880 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2e890 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
2e8a0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2e8b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
2e8c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
2e8d0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2e8e0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
2e8f0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
2e900 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
2e910 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
2e920 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
2e930 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
2e940 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2e950 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
2e960 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
2e970 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
2e980 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
2e990 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
2e9a0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
2e9b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e9c0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
2e9d0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2e9e0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
2e9f0 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
2ea00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ea10 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
2ea20 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2ea30 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
2ea40 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2ea50 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
2ea60 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
2ea70 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
2ea80 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2ea90 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2eaa0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
2eab0 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
2eac0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2ead0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2eae0 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
2eaf0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2eb00 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2eb10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
2eb20 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
2eb30 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
2eb40 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2eb50 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
2eb60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2eb70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
2eb80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
2eb90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
2eba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
2ebb0 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54  te_hook()..** ^T
2ebc0 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
2ebd0 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
2ebe0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2ebf0 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
2ec00 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
2ec10 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
2ec20 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2ec30 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
2ec40 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
2ec50 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
2ec60 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ked..** ^The thi
2ec70 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
2ec80 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
2ec90 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
2eca0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
2ecb0 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
2ecc0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
2ecd0 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
2ece0 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20  ed row..** ^The 
2ecf0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
2ed00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2ed10 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
2ed20 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  ow..** ^In the c
2ed30 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
2ed40 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
2ed50 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
2ed60 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
2ed70 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ce..**.** ^(The 
2ed80 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
2ed90 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
2eda0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
2edb0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
2edc0 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
2edd0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
2ede0 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
2edf0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  )^.**.** ^In the
2ee00 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2ee10 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
2ee20 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
2ee30 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
2ee40 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
2ee50 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
2ee60 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
2ee70 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
2ee80 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
2ee90 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20  ] clause.  ^Nor 
2eea0 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
2eeb0 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
2eec0 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
2eed0 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
2eee0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
2eef0 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
2ef00 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
2ef10 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2ef20 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
2ef30 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
2ef40 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2ef50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
2ef60 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
2ef70 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2ef80 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2ef90 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2efa0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2efb0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2efc0 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
2efd0 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
2efe0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
2eff0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f000 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
2f010 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
2f020 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
2f030 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
2f040 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2f050 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
2f060 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
2f070 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
2f080 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f090 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2f0a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2f0b0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2f0c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2f0d0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2f0e0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2f0f0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2f100 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  raph..**.** ^The
2f110 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2f120 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
2f130 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
2f140 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
2f150 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
2f160 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20   call.** on the 
2f170 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2f180 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
2f190 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
2f1a0 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44   first call on D
2f1b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2f1c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2f1d0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64  mmit_hook()] and
2f1e0 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
2f1f0 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e  ck_hook()].** in
2f200 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69  terfaces..*/.voi
2f210 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
2f220 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
2f230 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
2f240 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
2f250 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
2f260 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
2f270 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
2f280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f290 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
2f2a0 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
2f2b0 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  Cache.** KEYWORD
2f2c0 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  S: {shared cache
2f2d0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  }.**.** ^(This r
2f2e0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
2f2f0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
2f300 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
2f310 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
2f320 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
2f330 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
2f340 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
2f350 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63  nection | connec
2f360 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65  tions].** to the
2f370 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
2f380 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
2f390 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2f3a0 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e  nt is true.** an
2f3b0 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
2f3c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61  e argument is fa
2f3d0 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  lse.)^.**.** ^Ca
2f3e0 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
2f3f0 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
2f400 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
2f410 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68  e process..** Th
2f420 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
2f430 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
2f440 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72  ion 3.5.0. In pr
2f450 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
2f460 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69  SQLite,.** shari
2f470 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  ng was enabled o
2f480 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
2f490 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
2f4a0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ately..**.** ^(T
2f4b0 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
2f4c0 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
2f4d0 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
2f4e0 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
2f4f0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
2f500 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2f510 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2f520 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
2f530 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
2f540 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61   Existing databa
2f550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63  se connections c
2f560 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20  ontinue use the 
2f570 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20  sharing mode.** 
2f580 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65  that was in effe
2f590 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74  ct at the time t
2f5a0 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e  hey were opened.
2f5b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
2f5c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f5d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
2f5e0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
2f5f0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2f600 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
2f610 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
2f620 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2f630 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a  d otherwise.)^.*
2f640 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63  *.** ^Shared cac
2f650 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
2f660 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
2f670 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
2f680 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
2f690 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2f6a0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
2f6b0 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
2f6c0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
2f6d0 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
2f6e0 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
2f6f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f  ..**.** See Also
2f700 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65  :  [SQLite Share
2f710 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f  d-Cache Mode].*/
2f720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2f730 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
2f740 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2f750 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
2f760 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
2f770 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ory.**.** ^The s
2f780 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2f790 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
2f7a0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
2f7b0 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ee N bytes.** of
2f7c0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
2f7d0 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
2f7e0 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
2f7f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a  y allocations.**
2f800 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
2f810 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20  abase library.  
2f820 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
2f830 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
2f840 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
2f850 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
2f860 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
2f870 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
2f880 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  mory..** ^sqlite
2f890 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2f8a0 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
2f8b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
2f8c0 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
2f8d0 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
2f8e0 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
2f8f0 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
2f900 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  quested..** ^The
2f910 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2f920 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e  _memory() routin
2f930 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74  e is a no-op ret
2f940 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69  urning zero.** i
2f950 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20  f SQLite is not 
2f960 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
2f970 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
2f980 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
2f990 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f9a0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
2f9b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2f9c0 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
2f9d0 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
2f9e0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
2f9f0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
2fa00 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  imit() interface
2fa10 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
2fa20 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65   limit.** on the
2fa30 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20   amount of heap 
2fa40 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20  memory that may 
2fa50 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  be allocated by 
2fa60 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61  SQLite..** ^If a
2fa70 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63  n internal alloc
2fa80 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2fa90 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ed that would ex
2faa0 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ceed the.** soft
2fab0 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71   heap limit, [sq
2fac0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2fad0 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b  mory()] is invok
2fae0 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72  ed one or.** mor
2faf0 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20  e times to free 
2fb00 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65  up some space be
2fb10 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  fore the allocat
2fb20 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
2fb30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d  ..**.** ^The lim
2fb40 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
2fb50 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b  ft" because if [
2fb60 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2fb70 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e  memory()].** can
2fb80 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69  not free suffici
2fb90 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72  ent memory to pr
2fba0 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20  event the limit 
2fbb0 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65  from being excee
2fbc0 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ded,.** the memo
2fbd0 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
2fbe0 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63  anyway and the c
2fbf0 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
2fc00 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a   proceeds..**.**
2fc10 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20   ^A negative or 
2fc20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
2fc30 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
2fc40 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61  e is no soft hea
2fc50 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b  p limit and.** [
2fc60 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2fc70 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
2fc80 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2fc90 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68  en memory is exh
2fca0 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  austed..** ^The 
2fcb0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
2fcc0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2fcd0 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a  limit is zero..*
2fce0 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61  *.** ^(SQLite ma
2fcf0 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2fd00 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2fd10 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2fd20 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2fd30 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2fd40 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2fd50 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2fd60 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2fd70 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2fd80 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68  ification.)^  Th
2fd90 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69  is is why the li
2fda0 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  mit is.** called
2fdb0 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
2fdc0 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
2fdd0 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
2fde0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
2fdf0 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
2fe00 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
2fe10 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
2fe20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
2fe30 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
2fe40 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
2fe50 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
2fe60 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
2fe70 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
2fe80 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
2fe90 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
2fea0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2feb0 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
2fec0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
2fed0 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
2fee0 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
2fef0 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
2ff00 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
2ff10 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
2ff20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
2ff30 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
2ff40 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
2ff50 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
2ff60 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
2ff70 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
2ff80 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
2ff90 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
2ffa0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2ffb0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
2ffc0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ffd0 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
2ffe0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
2fff0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
30000 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
30010 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
30020 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
30030 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
30040 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
30050 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
30060 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
30070 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
30080 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
30090 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
300a0 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
300b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
300c0 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
300d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
300e0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
300f0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
30100 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
30110 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
30120 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
30130 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
30140 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
30150 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
30160 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
30170 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
30180 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
30190 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
301a0 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
301b0 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
301c0 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
301d0 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
301e0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
301f0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
30200 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
30210 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
30220 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
30230 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
30240 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
30250 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
30260 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
30270 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
30280 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
30290 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
302a0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
302b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
302c0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
302d0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
302e0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
302f0 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
30300 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
30310 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
30320 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
30330 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
30340 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
30350 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
30360 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
30370 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
30380 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
30390 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
303a0 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
303b0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
303c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
303d0 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
303e0 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
303f0 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
30400 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
30410 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
30420 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
30430 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
30440 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
30450 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
30460 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
30470 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
30480 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
30490 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
304a0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
304b0 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
304c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
304d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
304e0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
304f0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
30500 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
30510 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
30520 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
30530 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
30540 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
30550 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
30560 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
30570 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
30580 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
30590 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
305a0 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
305b0 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
305c0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
305d0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
305e0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
305f0 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
30600 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
30610 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
30620 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
30630 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
30640 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
30650 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
30660 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
30670 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
30680 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
30690 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
306a0 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
306b0 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
306c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
306d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
306e0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
306f0 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
30700 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
30710 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
30720 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
30730 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
30740 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
30750 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
30760 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
30770 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
30780 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
30790 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
307a0 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
307b0 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
307c0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
307d0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
307e0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
307f0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
30800 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
30810 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
30820 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
30830 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
30840 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
30850 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
30860 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
30870 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
30880 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
30890 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
308a0 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
308b0 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
308c0 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
308d0 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
308e0 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
308f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
30900 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
30910 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
30920 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
30930 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
30940 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
30950 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
30960 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
30970 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
30980 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
30990 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
309a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
309b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
309c0 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
309d0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
309e0 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
309f0 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
30a00 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
30a10 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
30a20 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
30a30 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
30a40 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
30a50 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
30a60 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
30a70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
30a80 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
30a90 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
30aa0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
30ab0 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
30ac0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
30ad0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
30ae0 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
30af0 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
30b00 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
30b10 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
30b20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
30b30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
30b40 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
30b50 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
30b60 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
30b70 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
30b80 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
30b90 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
30ba0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
30bb0 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
30bc0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
30bd0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
30be0 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
30bf0 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
30c00 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
30c10 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
30c20 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
30c30 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
30c40 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
30c50 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
30c60 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
30c70 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
30c80 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
30c90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
30ca0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
30cb0 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
30cc0 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
30cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
30ce0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
30cf0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
30d00 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
30d10 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
30d20 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
30d30 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
30d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
30d50 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
30d60 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
30d70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
30d80 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
30d90 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
30da0 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
30db0 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
30dc0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
30dd0 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
30de0 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
30df0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
30e00 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
30e10 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
30e20 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
30e30 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
30e40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
30e50 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
30e60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30e70 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
30e80 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
30e90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
30ea0 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
30eb0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
30ec0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
30ed0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
30ee0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
30ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
30f00 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
30f10 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
30f20 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
30f30 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
30f40 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
30f50 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
30f60 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
30f70 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
30f80 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
30f90 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
30fa0 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
30fb0 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
30fc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
30fd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
30fe0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
30ff0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
31000 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
31010 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
31020 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
31030 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
31040 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
31050 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
31060 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
31070 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
31080 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
31090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
310a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
310b0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
310c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
310d0 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
310e0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
310f0 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
31100 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
31110 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
31120 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
31130 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
31140 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
31150 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
31160 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
31170 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
31180 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
31190 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
311a0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
311b0 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
311c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
311d0 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
311e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
311f0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
31200 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
31210 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20  ading.**.** ^So 
31220 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
31230 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
31240 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
31250 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
31260 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
31270 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
31280 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
31290 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
312a0 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
312b0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
312c0 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
312d0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
312e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
312f0 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
31300 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
31310 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
31320 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
31330 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a   on and off..**.
31340 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
31350 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
31360 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63  default. See tic
31370 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43  ket #1863..** ^C
31380 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
31390 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
313a0 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20  nsion() routine 
313b0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a  with onoff==1.**
313c0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
313d0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
313e0 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
313f0 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
31400 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  ** it back off a
31410 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
31420 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
31430 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
31440 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
31450 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
31460 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c  REF: Automatical
31470 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  ly Load An Exten
31480 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  sions.**.** ^Thi
31490 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
314a0 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
314b0 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
314c0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
314d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
314e0 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
314f0 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
31500 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
31510 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64  ** to all new [d
31520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31530 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ons]..**.** ^(Th
31540 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
31550 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
31560 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  he extension ent
31570 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61  ry point.** in a
31580 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20  n array that is 
31590 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
315a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
315b0 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  .  That memory.*
315c0 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64  * is deallocated
315d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   by [sqlite3_res
315e0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
315f0 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  n()].)^.**.** ^T
31600 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  his function reg
31610 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73  isters an extens
31620 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
31630 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  that is.** autom
31640 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
31650 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
31660 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31670 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e  tion].** is open
31680 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
31690 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
316a0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
316b0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
316c0 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75  en_v2()]..** ^Du
316d0 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f  plicate extensio
316e0 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20  ns are detected 
316f0 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  so calling this 
31700 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69  routine.** multi
31710 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74  ple times with t
31720 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f  he same extensio
31730 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a  n is harmless..*
31740 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74  * ^Automatic ext
31750 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63  ensions apply ac
31760 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73  ross all threads
31770 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31780 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
31790 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69  void (*xEntryPoi
317a0 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a  nt)(void));../*.
317b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
317c0 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
317d0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
317e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63  *.** ^(This func
317f0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c  tion disables al
31800 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  l previously reg
31810 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69  istered automati
31820 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e  c.** extensions.
31830 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65   It undoes the e
31840 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69  ffect of all pri
31850 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  or.** [sqlite3_a
31860 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
31870 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20   calls.)^.**.** 
31880 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64  ^This function d
31890 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
318a0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
318b0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
318c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
318d0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
318e0 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  n(void);../*.** 
318f0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
31900 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
31910 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
31920 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
31930 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
31940 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
31950 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
31960 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
31970 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
31980 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
31990 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
319a0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
319b0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
319c0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
319d0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
319e0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
319f0 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
31a00 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
31a10 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
31a20 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
31a30 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
31a40 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
31a50 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
31a60 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
31a70 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
31a80 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
31a90 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
31aa0 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
31ab0 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
31ac0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
31ad0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
31ae0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
31af0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
31b00 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31b10 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
31b20 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
31b30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
31b40 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
31b50 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ule;../*.** CAPI
31b60 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
31b70 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ble Object.** KE
31b80 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
31b90 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
31ba0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
31bb0 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
31bc0 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
31bd0 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61  lled a a "virtua
31be0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
31bf0 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
31c00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31c10 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
31c20 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
31c30 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
31c40 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
31c50 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
31c60 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76  dule..**.** ^A v
31c70 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31c80 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
31c90 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
31ca0 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
31cb0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
31cc0 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
31cd0 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
31ce0 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
31cf0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
31d00 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
31d10 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
31d20 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
31d30 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61  ** ^The registra
31d40 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c  tion remains val
31d50 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  id until it is r
31d60 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66  eplaced by a dif
31d70 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65  ferent.** module
31d80 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64   or until the [d
31d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31da0 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65  on] closes.  The
31db0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74   content.** of t
31dc0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75  his structure mu
31dd0 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68  st not change wh
31de0 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74  ile it is regist
31df0 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79  ered with.** any
31e00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31e10 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  tion..*/.struct 
31e20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
31e30 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
31e40 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
31e50 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
31e60 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
31e70 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
31e80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
31e90 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
31ea0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
31eb0 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
31ec0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
31ed0 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
31ee0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
31ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
31f00 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
31f10 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
31f20 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31f30 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
31f40 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
31f50 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
31f60 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
31f70 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
31f80 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
31f90 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
31fa0 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
31fb0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
31fc0 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
31fd0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
31fe0 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
31ff0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
32000 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
32010 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
32020 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
32030 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
32040 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
32050 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
32060 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
32070 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
32080 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
32090 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
320a0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
320b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
320c0 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
320d0 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
320e0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
320f0 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
32100 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
32110 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
32120 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
32130 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
32140 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
32150 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
32160 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
32170 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
32180 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
32190 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
321a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
321b0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
321c0 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
321d0 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
321e0 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
321f0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
32200 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
32210 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
32220 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
32230 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
32240 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
32250 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
32260 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
32270 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
32280 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
32290 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
322a0 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
322b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
322c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
322d0 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
322e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
322f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32300 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
32310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32320 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
32330 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
32340 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
32350 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
32360 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
32370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
32380 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
32390 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
323a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
323b0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
323c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
323d0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
323e0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
323f0 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
32400 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
32410 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
32420 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
32430 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
32440 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
32450 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
32460 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
32470 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
32480 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
32490 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
324a0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
324b0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
324c0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
324d0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
324e0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
324f0 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
32500 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
32510 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
32520 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
32530 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
32540 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
32550 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
32560 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
32570 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
32580 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
32590 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f  column OP expr</
325a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
325b0 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
325c0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
325d0 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
325e0 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
325f0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
32600 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
32610 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e  traint[].op usin
32620 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  g one of the.** 
32630 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f  [SQLITE_INDEX_CO
32640 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51  NSTRAINT_EQ | SQ
32650 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32660 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29  RAINT_ values].)
32670 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78  ^.** ^(The index
32680 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
32690 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
326a0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
326b0 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
326c0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
326d0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
326e0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
326f0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
32700 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
32710 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
32720 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
32730 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
32740 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
32750 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
32760 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
32770 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
32780 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
32790 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
327a0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
327b0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
327c0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
327d0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
327e0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
327f0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
32800 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
32810 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
32820 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
32830 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
32840 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
32850 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
32860 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
32870 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
32880 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
32890 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
328a0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
328b0 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
328c0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
328d0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
328e0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
328f0 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
32900 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
32910 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
32920 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
32930 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
32940 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
32950 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
32960 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
32970 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
32980 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
32990 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
329a0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
329b0 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
329c0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
329d0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
329e0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
329f0 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
32a00 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
32a10 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
32a20 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
32a30 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
32a40 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
32a50 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
32a60 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
32a70 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
32a80 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
32a90 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
32aa0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
32ab0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
32ac0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
32ad0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
32ae0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
32af0 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
32b00 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
32b10 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
32b20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
32b30 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
32b40 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
32b50 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
32b60 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
32b70 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
32b80 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
32b90 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
32ba0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
32bb0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
32bc0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
32bd0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
32be0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
32bf0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
32c00 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
32c10 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
32c20 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
32c30 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
32c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
32c50 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
32c60 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
32c70 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
32c80 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
32c90 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
32ca0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
32cb0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
32cc0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
32cd0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
32ce0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
32cf0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
32d00 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
32d10 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
32d20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
32d30 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
32d40 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
32d50 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
32d60 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
32d70 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
32d80 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
32d90 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
32da0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
32db0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
32dc0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
32dd0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
32de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32df0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
32e00 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
32e10 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
32e20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
32e30 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
32e40 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
32e50 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
32e60 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
32e70 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
32e80 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
32e90 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
32ea0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
32eb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
32ec0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
32ed0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
32ee0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
32ef0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
32f00 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
32f10 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
32f20 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
32f30 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
32f40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32f50 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
32f60 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
32f70 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
32f80 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
32f90 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
32fa0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
32fb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
32fc0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
32fd0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
32fe0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
32ff0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
33000 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
33010 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
33020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
33030 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
33040 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
33050 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
33060 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
33070 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
33080 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
33090 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
330a0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
330b0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
330c0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
330d0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
330e0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
330f0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
33100 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
33110 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
33120 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
33130 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
33140 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
33150 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
33160 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
33170 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
33180 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
33190 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
331a0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
331b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
331c0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
331d0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
331e0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
331f0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
33200 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
33210 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
33220 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
33230 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
33240 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
33250 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
33260 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
33270 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
33280 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
33290 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
332a0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
332b0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
332c0 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70  le Constraint Op
332d0 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a  erator Codes.**.
332e0 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
332f0 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f  defined the allo
33300 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74  wed values for t
33310 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  he.** [sqlite3_i
33320 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73  ndex_info].aCons
33330 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c  traint[].op fiel
33340 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72  d.  Each value r
33350 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20  epresents.** an 
33360 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73  operator that is
33370 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74   part of a const
33380 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68  raint term in th
33390 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e wHERE clause o
333a0 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61  f.** a query tha
333b0 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61  t uses a [virtua
333c0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65  l table]..*/.#de
333d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
333e0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
333f0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
33400 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
33410 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
33420 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
33430 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
33440 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
33450 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
33460 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
33470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
33480 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
33490 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
334a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
334b0 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
334c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
334d0 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
334e0 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
334f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  entation.**.** ^
33500 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
33510 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
33520 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ter a new [virtu
33530 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
33540 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c   name..** ^Modul
33550 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
33560 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
33570 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
33580 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
33590 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
335a0 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20  dule and before 
335b0 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
335c0 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
335d0 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
335e0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  odule..**.** ^Th
335f0 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
33600 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
33610 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
33620 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
33630 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
33640 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  st parameter.  ^
33650 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
33660 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
33670 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
33680 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
33690 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
336a0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
336b0 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
336c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
336d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
336e0 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66  odule].   ^The f
336f0 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
33700 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
33710 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
33720 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
33730 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
33740 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
33750 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
33760 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
33770 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
33780 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
33790 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
337a0 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
337b0 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
337c0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ialized..**.** ^
337d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
337e0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69  te_module_v2() i
337f0 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66  nterface has a f
33800 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77  ifth parameter w
33810 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
33820 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
33830 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c  ctor for the pCl
33840 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69  ientData.  ^SQLi
33850 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
33860 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
33870 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
33880 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
33890 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
338a0 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
338b0 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
338c0 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c 69  nter.  ^The sqli
338d0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
338e0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
338f0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
33900 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
33910 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74  _module_v2() wit
33920 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74  h a NULL.** dest
33930 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73  ructor..*/.int s
33940 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
33950 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  dule(.  sqlite3 
33960 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
33970 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
33980 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
33990 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
339a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
339b0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
339c0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
339d0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
339e0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
339f0 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *p,   /* Methods
33a00 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
33a10 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65  */.  void *pClie
33a20 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20 20  ntData          
33a30 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
33a40 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
33a50 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  ect */.);.int sq
33a60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
33a70 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ule_v2(.  sqlite
33a80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
33a90 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
33aa0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
33ab0 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
33ac0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
33ad0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
33ae0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
33af0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
33b00 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
33b10 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f  e *p,   /* Metho
33b20 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
33b30 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c  e */.  void *pCl
33b40 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20  ientData,       
33b50 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
33b60 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
33b70 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28  nnect */.  void(
33b80 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
33b90 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20  )     /* Module 
33ba0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
33bb0 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ion */.);../*.**
33bc0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
33bd0 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63  al Table Instanc
33be0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
33bf0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
33c00 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  ab.**.** Every [
33c10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33c20 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
33c30 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
33c40 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20  lass.** of this 
33c50 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72 69  object to descri
33c60 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  be a particular 
33c70 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74  instance.** of t
33c80 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
33c90 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61  e].  Each subcla
33ca0 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61  ss will.** be ta
33cb0 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70  ilored to the sp
33cc0 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20  ecific needs of 
33cd0 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  the module imple
33ce0 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68  mentation..** Th
33cf0 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  e purpose of thi
33d00 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
33d10 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
33d20 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
33d30 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61  e.** common to a
33d40 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
33d50 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
33d60 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73   ^Virtual tables
33d70 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74   methods can set
33d80 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
33d90 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61  e by assigning a
33da0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69  .** string obtai
33db0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
33dc0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  3_mprintf()] to 
33dd0 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65  zErrMsg.  The me
33de0 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74  thod should.** t
33df0 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e  ake care that an
33e00 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69  y prior string i
33e10 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c  s freed by a cal
33e20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  l to [sqlite3_fr
33e30 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74  ee()].** prior t
33e40 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65  o assigning a ne
33e50 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72  w string to zErr
33e60 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68 65  Msg.  ^After the
33e70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
33e80 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
33e90 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
33ea0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
33eb0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
33ec0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
33ed0 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
33ee0 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
33ef0 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
33f00 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a  ill be zeroed..*
33f10 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
33f20 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20  _vtab {.  const 
33f30 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
33f40 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65  pModule;  /* The
33f50 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73   module for this
33f60 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a   virtual table *
33f70 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20  /.  int nRef;   
33f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33f90 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52      /* NO LONGER
33fa0 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 20   USED */.  char 
33fb0 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20  *zErrMsg;       
33fc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
33fd0 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d  ror message from
33fe0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
33ff0 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  () */.  /* Virtu
34000 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
34010 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
34020 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
34030 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
34040 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
34050 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
34060 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74  le Cursor Object
34070 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
34080 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
34090 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r {virtual table
340a0 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45   cursor}.**.** E
340b0 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
340c0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
340d0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
340e0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
340f0 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73  e.** following s
34100 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63  tructure to desc
34110 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61  ribe cursors tha
34120 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65  t point into the
34130 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
34140 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64  le] and are used
34150 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f  .** to loop thro
34160 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  ugh the virtual 
34170 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20  table.  Cursors 
34180 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
34190 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
341a0 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c  3_module.xOpen |
341b0 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f   xOpen] method o
341c0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64  f the module and
341d0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a   are destroyed.*
341e0 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  * by the [sqlite
341f0 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20  3_module.xClose 
34200 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64  | xClose] method
34210 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 75  .  Cursors are u
34220 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78  sed.** by the [x
34230 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d  Filter], [xNext]
34240 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75  , [xEof], [xColu
34250 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64  mn], and [xRowid
34260 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ] methods.** of 
34270 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
34280 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
34290 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
342a0 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
342b0 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
342c0 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
342d0 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
342e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
342f0 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
34300 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
34310 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
34320 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
34330 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
34340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
34350 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
34360 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
34370 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
34380 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
34390 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
343a0 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
343b0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
343c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
343d0 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
343e0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
343f0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
34400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34410 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61  clare The Schema
34420 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61   Of A Virtual Ta
34430 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ble.**.** ^The [
34440 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
34450 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
34460 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  of a.** [virtual
34470 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63   table module] c
34480 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61  all this interfa
34490 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65  ce.** to declare
344a0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65   the format (the
344b0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74   names and datat
344c0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ypes of the colu
344d0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76  mns) of.** the v
344e0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68  irtual tables th
344f0 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f  ey implement..*/
34500 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63  .int sqlite3_dec
34510 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
34520 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
34530 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  zSQL);../*.** CA
34540 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64  PI3REF: Overload
34550 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20   A Function For 
34560 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a  A Virtual Table.
34570 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20  **.** ^(Virtual 
34580 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69  tables can provi
34590 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69  de alternative i
345a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
345b0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75  f functions.** u
345c0 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46  sing the [xFindF
345d0 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20  unction] method 
345e0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
345f0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
34600 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76  .** But global v
34610 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65  ersions of those
34620 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75   functions.** mu
34630 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65  st exist in orde
34640 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64  r to be overload
34650 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ed.)^.**.** ^(Th
34660 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72  is API makes sur
34670 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  e a global versi
34680 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e  on of a function
34690 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
346a0 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e  ar.** name and n
346b0 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
346c0 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20  ers exists.  If 
346d0 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e  no such function
346e0 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72   exists.** befor
346f0 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61  e this API is ca
34700 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63  lled, a new func
34710 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e  tion is created.
34720 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  )^  ^The impleme
34730 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
34740 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61  e new function a
34750 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20  lways causes an 
34760 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20  exception to be 
34770 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74  thrown.  So.** t
34780 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
34790 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20  is not good for 
347a0 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65  anything by itse
347b0 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a  lf.  Its only.**
347c0 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62   purpose is to b
347d0 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20  e a placeholder 
347e0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
347f0 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a  n be overloaded.
34800 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c  ** by a [virtual
34810 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20   table]..*/.int 
34820 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
34830 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
34840 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
34850 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
34860 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
34870 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
34880 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
34890 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
348a0 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
348b0 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
348c0 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
348d0 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
348e0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
348f0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
34900 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
34910 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
34920 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
34930 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
34940 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
34950 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
34960 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
34970 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
34980 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
34990 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
349a0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
349b0 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
349c0 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
349d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
349e0 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
349f0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
34a00 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
34a10 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  mment..*/../*.**
34a20 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
34a30 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
34a40 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  LOB.** KEYWORDS:
34a50 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b   {BLOB handle} {
34a60 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a  BLOB handles}.**
34a70 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
34a80 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
34a90 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
34aa0 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a  n BLOB on which.
34ab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
34ac0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
34ad0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61  tal BLOB I/O] ca
34ae0 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n be performed..
34af0 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74  ** ^Objects of t
34b00 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
34b10 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
34b20 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
34b30 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
34b40 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
34b50 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68  close()]..** ^Th
34b60 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
34b70 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
34b80 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
34b90 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
34ba0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
34bb0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d  read or write sm
34bc0 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20  all subsections 
34bd0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20  of the BLOB..** 
34be0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c  ^The [sqlite3_bl
34bf0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
34c00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
34c10 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
34c20 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  OB in bytes..*/.
34c30 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
34c40 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
34c50 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
34c60 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
34c70 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
34c80 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a  mental I/O.**.**
34c90 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
34ca0 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42  es opens a [BLOB
34cb0 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65   handle | handle
34cc0 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f  ] to the BLOB lo
34cd0 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20  cated.** in row 
34ce0 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f  iRow, column zCo
34cf0 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62  lumn, table zTab
34d00 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
34d10 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20  Db;.** in other 
34d20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20  words, the same 
34d30 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20  BLOB that would 
34d40 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a  be selected by:.
34d50 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
34d60 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d     SELECT zColum
34d70 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c  n FROM zDb.zTabl
34d80 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20  e WHERE [rowid] 
34d90 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65  = iRow;.** </pre
34da0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  >)^.**.** ^If th
34db0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
34dc0 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  r is non-zero, t
34dd0 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
34de0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a  opened for read.
34df0 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 63  ** and write acc
34e00 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20 7a  ess. ^If it is z
34e10 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ero, the BLOB is
34e20 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
34e30 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20   access..** ^It 
34e40 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
34e50 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
34e60 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
34e70 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69   an index or pri
34e80 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72  mary .** key for
34e90 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66   writing. ^If [f
34ea0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
34eb0 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62  raints] are enab
34ec0 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e  led, it is .** n
34ed0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
34ee0 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
34ef0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b  t is part of a [
34f00 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77  child key] for w
34f10 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  riting..**.** ^N
34f20 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74  ote that the dat
34f30 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f  abase name is no
34f40 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74  t the filename t
34f50 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  hat contains.** 
34f60 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
34f70 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62   rather the symb
34f80 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65  olic name of the
34f90 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a   database that.*
34fa0 2a 20 61 70 70 65 61 72 73 20 61 66 74 65 72 20  * appears after 
34fb0 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20 77  the AS keyword w
34fc0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
34fd0 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73   is connected us
34fe0 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a  ing [ATTACH]..**
34ff0 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64   ^For the main d
35000 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68  atabase file, th
35010 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
35020 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46  is "main"..** ^F
35030 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20  or TEMP tables, 
35040 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
35050 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a  e is "temp"..**.
35060 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
35070 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
35080 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65  returned and the
35090 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   new [BLOB handl
350a0 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  e] is written.**
350b0 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68   to *ppBlob. Oth
350c0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
350d0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
350e0 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69  ed and *ppBlob i
350f0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61  s set.** to be a
35100 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e   null pointer.)^
35110 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
35120 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61 74  on sets the [dat
35130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35140 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  ] error code and
35150 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65   message.** acce
35160 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69  ssible via [sqli
35170 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61  te3_errcode()] a
35180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
35190 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65  sg()] and relate
351a0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20  d.** functions. 
351b0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 2a  ^Note that the *
351c0 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65 20  ppBlob variable 
351d0 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69 61  is always initia
351e0 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61  lized in a.** wa
351f0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74 20  y that makes it 
35200 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b  safe to invoke [
35210 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
35220 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62  se()] on *ppBlob
35230 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
35240 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f 72  f the success or
35250 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69 73   failure of this
35260 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20   routine..**.** 
35270 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74 68 61  ^(If the row tha
35280 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  t a BLOB handle 
35290 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64  points to is mod
352a0 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b  ified by an.** [
352b0 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45  UPDATE], [DELETE
352c0 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e  ], or by [ON CON
352d0 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65  FLICT] side-effe
352e0 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  cts.** then the 
352f0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d  BLOB handle is m
35300 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65  arked as "expire
35310 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74  d"..** This is t
35320 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d  rue if any colum
35330 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20  n of the row is 
35340 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20  changed, even a 
35350 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20  column.** other 
35360 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65  than the one the
35370 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
35380 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43  open on.)^.** ^C
35390 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
353a0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
353b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
353c0 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  write()] for.** 
353d0 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68  a expired BLOB h
353e0 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20  andle fail with 
353f0 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f  an return code o
35400 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
35410 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20 77  ..** ^(Changes w
35420 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c  ritten into a BL
35430 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  OB prior to the 
35440 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72  BLOB expiring ar
35450 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20  e not.** rolled 
35460 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69  back by the expi
35470 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c  ration of the BL
35480 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65  OB.  Such change
35490 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
354a0 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74  y.** commit if t
354b0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  he transaction c
354c0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
354d0 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  letion.)^.**.** 
354e0 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65  ^Use the [sqlite
354f0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
35500 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74  interface to det
35510 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20  ermine the size 
35520 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64  of.** the opened
35530 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a   blob.  ^The siz
35540 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20  e of a blob may 
35550 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62  not be changed b
35560 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  y this.** interf
35570 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55  ace.  Use the [U
35580 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61  PDATE] SQL comma
35590 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  nd to change the
355a0 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c   size of a.** bl
355b0 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ob..**.** ^The [
355c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
355d0 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71  oblob()] and [sq
355e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
355f0 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61  oblob()] interfa
35600 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62  ces.** and the b
35610 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f  uilt-in [zeroblo
35620 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  b] SQL function 
35630 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20  can be used, if 
35640 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63  desired,.** to c
35650 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20  reate an empty, 
35660 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62  zero-filled blob
35670 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61   in which to rea
35680 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67  d or write using
35690 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
356a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  ce..**.** To avo
356b0 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65  id a resource le
356c0 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b  ak, every open [
356d0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f  BLOB handle] sho
356e0 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  uld eventually.*
356f0 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  * be released by
35700 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
35710 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
35720 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
35730 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
35740 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
35750 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
35760 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
35770 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35780 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
35790 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
357a0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
357b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
357c0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
357d0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20  PI3REF: Close A 
357e0 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  BLOB Handle.**.*
357f0 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65  * ^Closes an ope
35800 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e  n [BLOB handle].
35810 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20  .**.** ^Closing 
35820 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75  a BLOB shall cau
35830 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  se the current t
35840 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f  ransaction to co
35850 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65  mmit.** if there
35860 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c   are no other BL
35870 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20  OBs, no pending 
35880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35890 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  nts, and the.** 
358a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
358b0 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63  ion is in [autoc
358c0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20  ommit mode]..** 
358d0 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77  ^If any writes w
358e0 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20  ere made to the 
358f0 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74  BLOB, they might
35900 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68   be held in cach
35910 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63  e.** until the c
35920 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69  lose operation i
35930 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e  f they will fit.
35940 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67  .**.** ^(Closing
35950 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20   the BLOB often 
35960 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67  forces the chang
35970 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73  es.** out to dis
35980 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20  k and so if any 
35990 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72  I/O errors occur
359a0 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65  , they will like
359b0 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74  ly occur.** at t
359c0 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  he time when the
359d0 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e   BLOB is closed.
359e0 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61    Any errors tha
359f0 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a  t occur during.*
35a00 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65  * closing are re
35a10 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d  ported as a non-
35a20 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75  zero return valu
35a30 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  e.)^.**.** ^(The
35a40 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
35a50 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
35a60 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
35a70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
35a80 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
35a90 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
35aa0 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a  ll closed.)^.**.
35ab0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
35ac0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
35ad0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75  null pointer (su
35ae0 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72  ch as would be r
35af0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20  eturned.** by a 
35b00 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b  failed call to [
35b10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35b20 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c  n()]) is a harml
35b30 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e  ess no-op..*/.in
35b40 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
35b50 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
35b60 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
35b70 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68  I3REF: Return Th
35b80 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65  e Size Of An Ope
35b90 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65  n BLOB.**.** ^Re
35ba0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69  turns the size i
35bb0 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42  n bytes of the B
35bc0 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76  LOB accessible v
35bd0 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65  ia the .** succe
35be0 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b  ssfully opened [
35bf0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20  BLOB handle] in 
35c00 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
35c10 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72  t.  ^The.** incr
35c20 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f  emental blob I/O
35c30 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e   routines can on
35c40 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77  ly read or overw
35c50 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a  riting existing.
35c60 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b  ** blob content;
35c70 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61   they cannot cha
35c80 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
35c90 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68  a blob..**.** Th
35ca0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
35cb0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
35cc0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
35cd0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
35ce0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
35cf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
35d00 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
35d10 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
35d20 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
35d30 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
35d40 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
35d50 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
35d60 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
35d70 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
35d80 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
35d90 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
35da0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
35db0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69  e behavior..*/.i
35dc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
35dd0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
35de0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
35df0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74  PI3REF: Read Dat
35e00 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e  a From A BLOB In
35e10 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a  crementally.**.*
35e20 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
35e30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  n is used to rea
35e40 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f  d data from an o
35e50 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
35e60 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c  ] into a.** call
35e70 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
35e80 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
35e90 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
35ea0 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  nto buffer Z.** 
35eb0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c  from the open BL
35ec0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
35ed0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29  offset iOffset.)
35ee0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73  ^.**.** ^If offs
35ef0 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65  et iOffset is le
35f00 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20  ss than N bytes 
35f10 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20  from the end of 
35f20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51  the BLOB,.** [SQ
35f30 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
35f40 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
35f50 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49  ata is read.  ^I
35f60 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69  f N or iOffset i
35f70 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
35f80 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ero, [SQLITE_ERR
35f90 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
35fa0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
35fb0 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a  ead..** ^The siz
35fc0 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61  e of the blob (a
35fd0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
35fe0 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
35ff0 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
36000 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
36010 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
36020 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
36030 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
36040 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72  ^An attempt to r
36050 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69  ead from an expi
36060 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  red [BLOB handle
36070 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  ] fails with an.
36080 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66  ** error code of
36090 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
360a0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
360b0 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ess, sqlite3_blo
360c0 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73  b_read() returns
360d0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f   SQLITE_OK..** O
360e0 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72  therwise, an [er
360f0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
36100 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36110 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
36120 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  d.)^.**.** This 
36130 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
36140 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
36150 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
36160 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
36170 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
36180 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
36190 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
361a0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
361b0 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
361c0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
361d0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
361e0 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
361f0 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
36200 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
36210 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
36220 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
36230 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
36240 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53  ehavior..**.** S
36250 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
36260 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e  3_blob_write()].
36270 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36280 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65  blob_read(sqlite
36290 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a  3_blob *, void *
362a0 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f  Z, int N, int iO
362b0 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
362c0 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44  API3REF: Write D
362d0 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20  ata Into A BLOB 
362e0 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a  Incrementally.**
362f0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
36300 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72  on is used to wr
36310 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e  ite data into an
36320 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
36330 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61  le] from a.** ca
36340 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
36350 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f  ffer. ^N bytes o
36360 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
36370 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
36380 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  r Z.** into the 
36390 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
363a0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
363b0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ffset..**.** ^If
363c0 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
363d0 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  e] passed as the
363e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
363f0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66  was not opened f
36400 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74  or.** writing (t
36410 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
36420 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
36430 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20  lob_open()] was 
36440 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66  zero),.** this f
36450 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
36460 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  [SQLITE_READONLY
36470 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ]..**.** ^This f
36480 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79  unction may only
36490 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74   modify the cont
364a0 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ents of the BLOB
364b0 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  ; it is.** not p
364c0 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65  ossible to incre
364d0 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ase the size of 
364e0 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69  a BLOB using thi
364f0 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66  s API..** ^If of
36500 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20  fset iOffset is 
36510 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65  less than N byte
36520 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f  s from the end o
36530 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b  f the BLOB,.** [
36540 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
36550 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
36560 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
36570 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c  .  ^If N is.** l
36580 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53  ess than zero [S
36590 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
365a0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
365b0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
365c0 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20  .** The size of 
365d0 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65  the BLOB (and he
365e0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  nce the maximum 
365f0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73  value of N+iOffs
36600 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  et).** can be de
36610 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74  termined using t
36620 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
36630 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
36640 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ace..**.** ^An a
36650 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
36660 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  to an expired [B
36670 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
36680 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
36690 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
366a0 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69  TE_ABORT].  ^Wri
366b0 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  tes to the BLOB 
366c0 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a  that occurred.**
366d0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f   before the [BLO
366e0 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65  B handle] expire
366f0 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64  d are not rolled
36700 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20   back by the.** 
36710 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
36720 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68  e handle, though
36730 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65   of course those
36740 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a   changes might.*
36750 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72  * have been over
36760 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73  written by the s
36770 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78  tatement that ex
36780 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68  pired the BLOB h
36790 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f  andle.** or by o
367a0 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74  ther independent
367b0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
367c0 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
367d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
367e0 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51  ite() returns SQ
367f0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65  LITE_OK..** Othe
36800 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
36810 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
36820 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
36830 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
36840 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  )^.**.** This ro
36850 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
36860 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
36870 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
36880 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
36890 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
368a0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
368b0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
368c0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
368d0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
368e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
368f0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
36900 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
36910 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
36920 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
36930 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
36940 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
36950 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
36960 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  avior..**.** See
36970 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36980 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f  blob_read()]..*/
36990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
369a0 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
369b0 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
369c0 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
369d0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
369e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
369f0 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d  tual File System
36a00 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41   Objects.**.** A
36a10 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
36a20 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
36a30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
36a40 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
36a50 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
36a60 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
36a70 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
36a80 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
36a90 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
36aa0 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
36ab0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
36ac0 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
36ad0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
36ae0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
36af0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
36b00 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
36b10 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
36b20 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
36b30 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
36b40 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
36b50 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
36b60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36b70 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e  e3_vfs_find() in
36b80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36b90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56  a pointer to a V
36ba0 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  FS given its nam
36bb0 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65  e..** ^Names are
36bc0 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
36bd0 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a  .** ^Names are z
36be0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
36bf0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
36c00 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
36c10 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70   match, a NULL p
36c20 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
36c30 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e  ed..** ^If zVfsN
36c40 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
36c50 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
36c60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
36c70 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61  .** ^New VFSes a
36c80 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  re registered wi
36c90 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  th sqlite3_vfs_r
36ca0 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45  egister()..** ^E
36cb0 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f  ach new VFS beco
36cc0 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  mes the default 
36cd0 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44  VFS if the makeD
36ce0 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e  flt flag is set.
36cf0 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46  .** ^The same VF
36d00 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  S can be registe
36d10 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
36d20 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72  es without injur
36d30 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61  y..** ^To make a
36d40 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
36d50 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
36d60 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
36d70 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
36d80 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
36d90 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69   set.  If two di
36da0 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69  fferent VFSes wi
36db0 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e  th the.** same n
36dc0 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72  ame are register
36dd0 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ed, the behavior
36de0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
36df0 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72  If a.** VFS is r
36e00 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistered with a
36e10 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55   name that is NU
36e20 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73  LL or an empty s
36e30 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74  tring,.** then t
36e40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
36e50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
36e60 5e 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46  ^Unregister a VF
36e70 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
36e80 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
36e90 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
36ea0 2a 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 75  * ^(If the defau
36eb0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
36ec0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
36ed0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
36ee0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
36ef0 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
36f00 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
36f10 61 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a  arbitrary.)^.*/.
36f20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c  sqlite3_vfs *sql
36f30 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f  ite3_vfs_find(co
36f40 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61  nst char *zVfsNa
36f50 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  me);.int sqlite3
36f60 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71  _vfs_register(sq
36f70 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
36f80 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73  makeDflt);.int s
36f90 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
36fa0 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
36fb0 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s*);../*.** CAPI
36fc0 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a  3REF: Mutexes.**
36fd0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
36fe0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72  ore uses these r
36ff0 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65  outines for thre
37000 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a  ad.** synchroniz
37010 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68  ation. Though th
37020 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ey are intended 
37030 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
37040 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63  use by SQLite, c
37050 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ode that links a
37060 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73  gainst SQLite is
37070 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f  .** permitted to
37080 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
37090 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
370a0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75  * The SQLite sou
370b0 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e  rce code contain
370c0 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  s multiple imple
370d0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66  mentations.** of
370e0 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
370f0 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
37100 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
37110 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
37120 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
37130 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
37140 6d 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  me.  ^(The follo
37150 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  wing.** implemen
37160 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69  tations are avai
37170 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c  lable in the SQL
37180 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20  ite core:.**.** 
37190 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  <ul>.** <li>   S
371a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a  QLITE_MUTEX_OS2.
371b0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
371c0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a  _MUTEX_PTHREAD.*
371d0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
371e0 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69  MUTEX_W32.** <li
371f0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
37200 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _NOOP.** </ul>)^
37210 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  .**.** ^The SQLI
37220 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d  TE_MUTEX_NOOP im
37230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
37240 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65  a set of routine
37250 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  s.** that does n
37260 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61  o real locking a
37270 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  nd is appropriat
37280 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20  e for use in.** 
37290 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  a single-threade
372a0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  d application.  
372b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
372c0 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45  X_OS2,.** SQLITE
372d0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20  _MUTEX_PTHREAD, 
372e0 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
372f0 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74  _W32 implementat
37300 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72  ions.** are appr
37310 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
37320 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61  on OS/2, Unix, a
37330 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a  nd Windows..**.*
37340 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73  * ^(If SQLite is
37350 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
37360 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
37370 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73  APPDEF preproces
37380 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66  sor.** macro def
37390 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51  ined (with "-DSQ
373a0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
373b0 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d  F=1"), then no m
373c0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
373d0 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64  tation is includ
373e0 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
373f0 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ary. In this cas
37400 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  e the.** applica
37410 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
37420 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20   a custom mutex 
37430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
37440 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
37450 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
37460 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  ] option of the 
37470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
37480 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66   function.** bef
37490 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69  ore calling sqli
374a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
374b0 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75   or any other pu
374c0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a  blic sqlite3_.**
374d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
374e0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
374f0 74 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a  tialize().)^.**.
37500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37510 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f  mutex_alloc() ro
37520 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20  utine allocates 
37530 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61  a new.** mutex a
37540 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
37550 6e 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66 20  nter to it. ^If 
37560 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a  it returns NULL.
37570 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ** that means th
37580 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64  at a mutex could
37590 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65   not be allocate
375a0 64 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77  d.  ^SQLite.** w
375b0 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73  ill unwind its s
375c0 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20  tack and return 
375d0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68 65  an error.  ^(The
375e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
375f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
37600 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20  loc() is one of 
37610 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
37620 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  nstants:.**.** <
37630 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
37640 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
37650 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
37660 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
37670 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
37680 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
37690 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ER.** <li>  SQLI
376a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
376b0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  MEM.** <li>  SQL
376c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
376d0 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _MEM2.** <li>  S
376e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
376f0 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20  IC_PRNG.** <li> 
37700 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
37710 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e  ATIC_LRU.** <li>
37720 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
37730 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f  TATIC_LRU2.** </
37740 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ul>)^.**.** ^The
37750 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74   first two const
37760 61 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ants (SQLITE_MUT
37770 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49  EX_FAST and SQLI
37780 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
37790 56 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c  VE).** cause sql
377a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
377b0 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20  () to create.** 
377c0 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e 54  a new mutex.  ^T
377d0 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
377e0 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
377f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
37800 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
37810 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
37820 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
37830 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
37840 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  s used..** The m
37850 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
37860 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
37870 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74  d to make a dist
37880 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
37890 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
378a0 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51  RECURSIVE and SQ
378b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
378c0 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
378d0 74 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c  t want to.  ^SQL
378e0 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65  ite will only re
378f0 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76  quest a recursiv
37900 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61  e mutex in.** ca
37910 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61  ses where it rea
37920 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20  lly needs one.  
37930 5e 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e  ^If a faster non
37940 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78  -recursive mutex
37950 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37960 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
37970 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74  on the host plat
37980 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20  form, the mutex 
37990 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67  subsystem.** mig
379a0 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61  ht return such a
379b0 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e   mutex in respon
379c0 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54  se to SQLITE_MUT
379d0 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e  EX_FAST..**.** ^
379e0 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65  The other allowe
379f0 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  d parameters to 
37a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
37a10 6c 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67 20  loc() (anything 
37a20 6f 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51  other.** than SQ
37a30 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
37a40 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
37a50 5f 52 45 43 55 52 53 49 56 45 29 20 65 61 63 68  _RECURSIVE) each
37a60 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
37a70 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
37a80 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
37a90 65 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69 63  ex.  ^Six static
37aa0 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20   mutexes are.** 
37ab0 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72  used by the curr
37ac0 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  ent version of S
37ad0 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76  QLite.  Future v
37ae0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
37af0 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64  e.** may add add
37b00 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d  itional static m
37b10 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20  utexes.  Static 
37b20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20  mutexes are for 
37b30 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
37b40 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20  by SQLite only. 
37b50 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
37b60 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75  at use SQLite mu
37b70 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  texes should.** 
37b80 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e  use only the dyn
37b90 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74  amic mutexes ret
37ba0 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f  urned by SQLITE_
37bb0 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a  MUTEX_FAST or.**
37bc0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
37bd0 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e  CURSIVE..**.** ^
37be0 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65  Note that if one
37bf0 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20   of the dynamic 
37c00 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73  mutex parameters
37c10 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46   (SQLITE_MUTEX_F
37c20 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45  AST.** or SQLITE
37c30 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
37c40 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73  ) is used then s
37c50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
37c60 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  oc().** returns 
37c70 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65  a different mute
37c80 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e  x on every call.
37c90 20 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20 73    ^But for the s
37ca0 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74  tatic.** mutex t
37cb0 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d  ypes, the same m
37cc0 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64  utex is returned
37cd0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74   on every call t
37ce0 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73  hat has.** the s
37cf0 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e  ame type number.
37d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37d10 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29  te3_mutex_free()
37d20 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63   routine dealloc
37d30 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c  ates a previousl
37d40 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64  y.** allocated d
37d50 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e  ynamic mutex.  ^
37d60 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
37d70 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
37d80 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
37d90 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
37da0 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64  llocates.  The d
37db0 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d  ynamic mutexes m
37dc0 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a  ust not be in.**
37dd0 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61   use when they a
37de0 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20  re deallocated. 
37df0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
37e00 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
37e10 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
37e20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
37e30 20 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c   behavior.  ^SQL
37e40 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f  ite never deallo
37e50 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69  cates.** a stati
37e60 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e  c mutex..**.** ^
37e70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
37e80 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71  x_enter() and sq
37e90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37ea0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  ) routines attem
37eb0 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61  pt.** to enter a
37ec0 20 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f   mutex.  ^If ano
37ed0 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
37ee0 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
37ef0 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
37f00 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
37f10 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
37f20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
37f30 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
37f40 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
37f50 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d    ^The sqlite3_m
37f60 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
37f70 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51  face returns [SQ
37f80 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e  LITE_OK].** upon
37f90 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72   successful entr
37fa0 79 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63 72  y.  ^(Mutexes cr
37fb0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53  eated using.** S
37fc0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
37fd0 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74  RSIVE can be ent
37fe0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
37ff0 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20  mes by the same 
38000 74 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75  thread..** In su
38010 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
38020 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
38030 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
38040 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
38050 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
38060 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
38070 72 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20 73  r.)^  ^(If the s
38080 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
38090 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
380a0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
380b0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
380c0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
380d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
380e0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
380f0 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20  ever exhibit.** 
38100 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e  such behavior in
38110 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20   its own use of 
38120 6d 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  mutexes.)^.**.**
38130 20 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73 20   ^(Some systems 
38140 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69  (for example, Wi
38150 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74  ndows 95) do not
38160 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65   support the ope
38170 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ration.** implem
38180 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  ented by sqlite3
38190 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f  _mutex_try().  O
381a0 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c  n those systems,
381b0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
381c0 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ry().** will alw
381d0 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ays return SQLIT
381e0 45 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c  E_BUSY.  The SQL
381f0 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76  ite core only ev
38200 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74  er uses.** sqlit
38210 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61  e3_mutex_try() a
38220 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s an optimizatio
38230 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63  n so this is acc
38240 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72  eptable behavior
38250 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
38260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
38270 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69  ve() routine exi
38280 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20  ts a mutex that 
38290 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
382a0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
382b0 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 20   same thread.   
382c0 5e 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  ^(The behavior.*
382d0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69  * is undefined i
382e0 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e  f the mutex is n
382f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ot currently ent
38300 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63  ered by the.** c
38310 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72  alling thread or
38320 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
38330 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51  y allocated.  SQ
38340 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
38350 65 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a  er do either.)^.
38360 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
38370 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
38380 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c  3_mutex_enter(),
38390 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
383a0 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69  ry(), or.** sqli
383b0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
383c0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
383d0 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68  ter, then all th
383e0 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ree routines.** 
383f0 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73  behave as no-ops
38400 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
38410 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  : [sqlite3_mutex
38420 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71  _held()] and [sq
38430 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
38440 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  eld()]..*/.sqlit
38450 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65  e3_mutex *sqlite
38460 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e  3_mutex_alloc(in
38470 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
38480 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69  _mutex_free(sqli
38490 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
384a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
384b0 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75  enter(sqlite3_mu
384c0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
384d0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c  e3_mutex_try(sql
384e0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
384f0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
38500 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d  _leave(sqlite3_m
38510 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utex*);../*.** C
38520 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d  API3REF: Mutex M
38530 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
38540 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
38550 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
38560 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f  e defines the lo
38570 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73  w-level routines
38580 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f  .** used to allo
38590 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74  cate and use mut
385a0 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61  exes..**.** Usua
385b0 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74  lly, the default
385c0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
385d0 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20  ations provided 
385e0 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a  by SQLite are.**
385f0 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77   sufficient, how
38600 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61  ever the user ha
38610 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20  s the option of 
38620 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63  substituting a c
38630 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ustom.** impleme
38640 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63  ntation for spec
38650 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65  ialized deployme
38660 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66  nts or systems f
38670 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a  or which SQLite.
38680 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  ** does not prov
38690 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69  ide a suitable i
386a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49  mplementation. I
386b0 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65  n this case, the
386c0 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73   user.** creates
386d0 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61   and populates a
386e0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
386f0 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  is structure to 
38700 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  pass.** to sqlit
38710 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e  e3_config() alon
38720 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  g with the [SQLI
38730 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
38740 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69   option..** Addi
38750 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73  tionally, an ins
38760 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
38770 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75  ructure can be u
38780 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74  sed as an.** out
38790 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65  put variable whe
387a0 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73  n querying the s
387b0 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75  ystem for the cu
387c0 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69  rrent mutex.** i
387d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75  mplementation, u
387e0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
387f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
38800 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ] option..**.** 
38810 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20  ^The xMutexInit 
38820 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62  method defined b
38830 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
38840 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a   is invoked as.*
38850 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d  * part of system
38860 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
38870 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
38880 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63  nitialize() func
38890 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d  tion..** ^The xM
388a0 75 74 65