/ Hex Artifact Content
Login

Artifact 60f4fcfe18bcb53ed0002989837b68aeeba79a5e:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 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 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5630: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5640: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5650: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
5660: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
5670: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5690: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
56a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
56b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
56c0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
56d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
56e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
56f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5700: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5710: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5720: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5730: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5740: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5750: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5770: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5780: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5790: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
57a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
57b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
57d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
57e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
57f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5800: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5810: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5820: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5830: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5840: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5850: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5870: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5880: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5890: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
58a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
58b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
58c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
58d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
58e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
58f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5900: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5920: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5930: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5940: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5950: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5960: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5970: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5980: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
59a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
59b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
59c0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
59d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
59e0: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
59f0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5a00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5a10: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a20: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5a40: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a50: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5a60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5a70: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a80: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
5a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5aa0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5ab0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
5ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5ad0: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
5ae0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5b00: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
5b10: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
5b20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
5b30: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
5b40: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
5b50: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5b60: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
5b70: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
5b80: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b90: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
5ba0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
5bb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5bc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5bd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5be0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5bf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5c00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5c10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5c20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5c30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5c40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5c50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5c60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5c90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5ca0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5cb0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5cc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5cd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5cf0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5d20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5d30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5d40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5d50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5d60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5d70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5d80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5d90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5da0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5db0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5dc0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5dd0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5de0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5df0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5e00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5e10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5e20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5e30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5e40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5e50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5e60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5e70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5e80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5e90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5ea0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5eb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5ec0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5ed0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5ee0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ef0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5f00: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
5f10: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
5f20: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
5f30: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
5f40: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
5f50: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
5f60: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
5f70: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
5f80: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
5f90: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
5fa0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
5fb0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
5fc0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
5fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5fe0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
5ff0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
6000: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6010: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
6020: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
6030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6040: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6050: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6060: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
6070: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
6080: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
6090: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
60a0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
60b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
60c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
60d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
60e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
60f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6100: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6110: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6120: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6130: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6150: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
6160: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
6170: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
6180: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
6190: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
61a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
61b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
61c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
61d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
61e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
61f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6200: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6210: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6220: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6230: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6240: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6250: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
6260: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
6270: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
6280: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
6290: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
62a0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
62b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
62c0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
62d0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
62e0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
62f0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6300: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
6310: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
6320: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
6330: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
6340: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
6350: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
6360: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
6370: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
6380: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
6390: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
63a0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
63b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63c0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
63d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65   xOpen method se
63e0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
63f0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6400: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
6410: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
6420: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
6430: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
6440: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
6450: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
6460: 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65   if the xOpen re
6470: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
6480: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
6490: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
64a0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
64b0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
64c0: 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20  failed xOpen.** 
64d0: 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e  is for the xOpen
64e0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
64f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6500: 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c  s element to NUL
6510: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
6520: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
6530: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
6540: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
6550: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
6560: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
6570: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
6580: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
6590: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
65a0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
65b0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
65c0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
65d0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
65e0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
65f0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
6600: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
6610: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
6620: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
6630: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
6640: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
6650: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
6660: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
6670: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6680: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
6690: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
66a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
66b0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
66c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
66d0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
66e0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
66f0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6700: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6710: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
6720: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6730: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
6740: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
6750: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
6760: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
6770: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
6780: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
6790: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
67a0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
67b0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
67c0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
67d0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
67e0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
67f0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
6800: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
6810: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
6820: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
6830: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
6840: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
6850: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
6860: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
6870: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
6880: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
6890: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
68a0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
68b0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
68c0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
68d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
68e0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
68f0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
6900: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
6910: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6920: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
6930: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
6940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
6950: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
6960: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
6970: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6980: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
6990: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
69a0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
69b0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
69c0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
69d0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
69e0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
69f0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6a00: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6a10: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6a20: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6a30: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6a40: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6a50: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6a60: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6a70: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
6a80: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
6a90: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
6aa0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
6ab0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
6ac0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
6ad0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6ae0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6af0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6b00: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
6b10: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
6b20: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
6b30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6b40: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
6b50: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
6b60: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
6b70: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
6b80: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
6b90: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
6ba0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
6bb0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
6bc0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
6bd0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
6be0: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
6bf0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
6c00: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
6c10: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
6c20: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
6c30: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
6c40: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
6c50: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
6c60: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
6c70: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
6c80: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
6c90: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
6ca0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
6cb0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
6cc0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6cd0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
6ce0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
6cf0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
6d00: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
6d10: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
6d20: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
6d30: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6d40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6d70: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
6d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6d90: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6da0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6db0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6dd0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6de0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
6df0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6e00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6e10: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
6e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e30: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
6e40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e50: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
6e60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6e70: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
6e80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
6e90: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
6ea0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
6eb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ec0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6ed0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6ee0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6ef0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f10: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
6f20: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6f30: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6f40: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6f50: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6f60: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6f70: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6f80: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6f90: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6fa0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6fb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6fc0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6fd0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6fe0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6ff0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
7000: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
7010: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
7020: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
7030: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
7040: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
7050: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
7060: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
7070: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
7080: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7090: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
70a0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
70b0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
70c0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
70d0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
70e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
70f0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
7100: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
7110: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
7120: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
7130: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
7140: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
7150: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
7160: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
7170: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
7180: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
7190: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
71a0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
71b0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
71c0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
71d0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
71e0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
71f0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
7200: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7210: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
7220: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
7230: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7240: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
7250: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
7260: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
7270: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7280: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7290: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
72a0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
72b0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
72c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
72d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
72e0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
72f0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
7300: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
7310: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
7320: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7330: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
7340: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
7350: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
7360: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
7370: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
7380: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7390: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
73a0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
73b0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
73c0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
73d0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
73e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
73f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
7400: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
7410: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7420: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
7430: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
7440: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7450: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
7460: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
7470: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
7480: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7490: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
74a0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
74b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
74c0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
74d0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
74e0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
74f0: 2a 78 53 68 6d 4f 70 65 6e 29 28 73 71 6c 69 74  *xShmOpen)(sqlit
7500: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7510: 20 28 2a 78 53 68 6d 53 69 7a 65 29 28 73 71 6c   (*xShmSize)(sql
7520: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7530: 72 65 71 53 69 7a 65 2c 20 69 6e 74 20 2a 70 4e  reqSize, int *pN
7540: 65 77 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  ewSize);.  int (
7550: 2a 78 53 68 6d 47 65 74 29 28 73 71 6c 69 74 65  *xShmGet)(sqlite
7560: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 72 65 71  3_file*, int req
7570: 53 69 7a 65 2c 20 69 6e 74 20 2a 70 53 69 7a 65  Size, int *pSize
7580: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
7590: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
75a0: 52 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33  Release)(sqlite3
75b0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
75c0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
75d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
75e0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
75f0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7600: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7620: 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f 73 65   int (*xShmClose
7630: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7640: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7650: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7660: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7670: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
7680: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
7690: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
76a0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
76b0: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
76c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
76d0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
76e0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
76f0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
7700: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
7710: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
7720: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7730: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
7740: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7750: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
7760: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7770: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
7780: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7790: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
77a0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
77b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
77c0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
77d0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
77e0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
77f0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
7800: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
7810: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
7820: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
7830: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7840: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
7850: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
7860: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7870: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7880: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
7890: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
78a0: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
78b0: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
78c0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
78d0: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
78e0: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
78f0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
7900: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
7910: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
7920: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
7930: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
7940: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ed..**.** The [S
7950: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
7960: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
7970: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
7980: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
7990: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
79a0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
79b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
79c0: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
79d0: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
79e0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
79f0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
7a00: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
7a10: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
7a20: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
7a30: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
7a40: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
7a50: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
7a60: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
7a70: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
7a80: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
7a90: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
7aa0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
7ab0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
7ac0: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2f  e run faster..*/
7ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7ae0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
7af0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
7b00: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
7b10: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32  PROXYFILE      2
7b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7b30: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
7b40: 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65  E      3.#define
7b50: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
7b60: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 34  NO             4
7b70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7b80: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
7b90: 20 20 20 20 20 20 20 35 0a 0a 2f 2a 0a 2a 2a 20         5../*.** 
7ba0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7bb0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7bc0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7bd0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7be0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7bf0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7c00: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7c10: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7c20: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7c30: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7c40: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
7c50: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
7c60: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
7c70: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
7c80: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
7c90: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
7ca0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7cb0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7cc0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7cd0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7ce0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7cf0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7d00: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7d10: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7d20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7d30: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7d40: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
7d50: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
7d60: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7d70: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
7d80: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
7d90: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
7da0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7db0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7dc0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7dd0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7de0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7df0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7e00: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7e10: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7e20: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7e30: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7e40: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
7e50: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
7e60: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
7e70: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
7e80: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
7e90: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
7ea0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7eb0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7ec0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7ed0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7ee0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7ef0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7f00: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7f10: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7f20: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7f30: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7f40: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7f50: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7f60: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7f70: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7f80: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7f90: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7fa0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7fb0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7fc0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7fd0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7fe0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7ff0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
8000: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
8010: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
8020: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
8030: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
8040: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
8050: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
8060: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
8070: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
8080: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
8090: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
80a0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
80b0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
80c0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
80d0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
80e0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
80f0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
8100: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
8110: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
8120: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
8130: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
8140: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
8150: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
8160: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
8170: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
8180: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
8190: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
81a0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
81b0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
81c0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
81d0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
81e0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
81f0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
8200: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
8210: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
8220: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
8230: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
8240: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
8250: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
8260: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
8270: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
8280: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
8290: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
82a0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
82b0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
82c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
82d0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
82e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
82f0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
8300: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
8310: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
8320: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
8330: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
8340: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
8350: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8360: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8370: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8380: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8390: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
83a0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
83b0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
83c0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
83d0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
83e0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
83f0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
8400: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
8410: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
8420: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
8430: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
8440: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
8450: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
8460: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
8470: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
8480: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
8490: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
84a0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
84b0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
84c0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
84d0: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
84e0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
84f0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8500: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8510: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8520: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8530: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8540: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8550: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8560: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8570: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8580: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8590: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
85a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
85b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
85c0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
85d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
85e0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
85f0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8600: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8610: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8620: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8630: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8640: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8650: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8660: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8670: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8680: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8690: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
86a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
86b0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
86c0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
86d0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
86e0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
86f0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8700: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8710: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8720: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8730: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8740: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
8750: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
8760: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
8770: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
8780: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
8790: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
87a0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
87b0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
87c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87d0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
87e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
87f0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8800: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8810: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8820: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8830: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8840: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
8850: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
8860: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
8870: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
8880: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8890: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
88a0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
88b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
88c0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
88d0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
88e0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
88f0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8900: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8910: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8920: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8930: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8940: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
8950: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
8960: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
8970: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
8980: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
8990: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
89a0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
89b0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
89c0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
89d0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
89e0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
89f0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8a00: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8a10: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8a20: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8a30: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8a40: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
8a50: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
8a60: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
8a70: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
8a80: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
8a90: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
8aa0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8ab0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8ac0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8ad0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8ae0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8af0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8b00: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8b10: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8b20: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8b30: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8b40: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
8b50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
8b60: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
8b70: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8b80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8b90: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
8ba0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8bb0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8bc0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8bd0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8be0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8bf0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8c00: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8c10: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8c20: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8c30: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8c40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
8c50: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
8c60: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
8c70: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
8c80: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
8c90: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
8ca0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8cb0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8cc0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8cd0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8ce0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8cf0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8d00: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8d10: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8d20: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8d30: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8d40: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
8d50: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
8d60: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
8d70: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
8d80: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
8d90: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
8da0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8db0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8dc0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8dd0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8de0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8df0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8e00: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8e10: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8e20: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8e30: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8e40: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
8e50: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
8e60: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
8e70: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
8e80: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
8e90: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
8ea0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8eb0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8ec0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8ed0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8ee0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8ef0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8f00: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8f10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8f20: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8f30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8f40: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8f50: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8f60: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8f70: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8f80: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8f90: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8fa0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8fb0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8fc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8fd0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8fe0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8ff0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
9000: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
9010: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
9020: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
9030: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
9040: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
9050: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9060: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
9070: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
9080: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
9090: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
90a0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
90b0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
90c0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
90d0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
90e0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
90f0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
9100: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9110: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
9120: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
9130: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
9140: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
9150: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
9160: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
9170: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
9180: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
9190: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
91a0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
91b0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
91c0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
91d0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
91e0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
91f0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
9200: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
9210: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
9220: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
9230: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9240: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
9250: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
9260: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
9270: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
9280: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
9290: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
92a0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
92b0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
92c0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
92d0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
92e0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
92f0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
9300: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
9310: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
9320: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
9330: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
9340: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
9350: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
9360: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
9370: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
9380: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
9390: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
93a0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
93b0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
93c0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
93d0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
93e0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
93f0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
9400: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
9410: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
9420: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
9430: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
9440: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
9450: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
9460: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
9470: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
9480: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
9490: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
94a0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
94b0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
94c0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
94d0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
94e0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
94f0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9500: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9510: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9520: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9530: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9540: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
9550: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9560: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9570: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9580: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9590: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
95a0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
95b0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
95c0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
95d0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
95e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
95f0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
9600: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9610: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9620: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9630: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9640: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9650: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9660: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9670: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9680: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9690: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
96a0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
96b0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
96c0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
96d0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
96e0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
96f0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
9700: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9710: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9720: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9730: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9740: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9750: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9760: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9770: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9780: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9790: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
97a0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
97b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
97c0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
97d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
97e0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
97f0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
9800: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9810: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9820: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9830: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9840: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9850: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9860: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9870: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9880: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9890: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
98a0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
98b0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
98c0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
98d0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
98e0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
98f0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
9900: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9910: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9920: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9930: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9940: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9950: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9960: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9970: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9980: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9990: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
99a0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
99b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
99c0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
99d0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
99e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
99f0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
9a00: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9a10: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9a20: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9a30: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9a40: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9a50: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9a60: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9a70: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9a80: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9a90: 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
9aa0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9ab0: 20 63 68 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e   char *zOld, con
9ac0: 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69  st char *zNew, i
9ad0: 6e 74 20 64 69 72 53 79 6e 63 29 3b 0a 20 20 69  nt dirSync);.  i
9ae0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
9af0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
9b00: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
9b10: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
9b20: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
9b30: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
9b40: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
9b50: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
9b60: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
9b70: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
9b80: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
9b90: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
9ba0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
9bb0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
9bc0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
9bd0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
9be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9bf0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
9c00: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
9c10: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
9c20: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
9c30: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
9c40: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
9c50: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
9c60: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
9c70: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
9c80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
9c90: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9ca0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
9cb0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
9cc0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
9cd0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
9ce0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9cf0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
9d00: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
9d10: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
9d20: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9d30: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
9d40: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9d50: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
9d60: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9d70: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9d80: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
9d90: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9da0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9db0: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9dc0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9dd0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
9de0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
9df0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
9e00: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9e10: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
9e20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9e30: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9e50: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9e60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9e70: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
9e80: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
9e90: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
9ea0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
9eb0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
9ec0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
9ed0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
9ee0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
9ef0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
9f00: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
9f10: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
9f20: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
9f30: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
9f40: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
9f50: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
9f60: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
9f70: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
9f80: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
9f90: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
9fa0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
9fb0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
9fc0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
9fd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
9fe0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
9ff0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
a000: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
a010: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
a020: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
a030: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
a040: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
a050: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
a060: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
a070: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
a080: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
a090: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
a0a0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
a0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
a0c0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
a0d0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
a0e0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
a0f0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
a100: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
a110: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
a120: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
a130: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
a140: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
a150: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
a160: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
a170: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
a180: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
a190: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
a1a0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
a1b0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
a1c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
a1d0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
a1e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
a1f0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
a200: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
a210: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
a220: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
a230: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
a240: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
a250: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
a260: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
a270: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
a280: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
a290: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
a2a0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
a2b0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
a2c0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
a2d0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
a2e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
a2f0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
a300: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
a310: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
a320: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
a330: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
a340: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a350: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
a360: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
a370: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
a380: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
a390: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
a3a0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
a3b0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
a3c0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
a3d0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
a3e0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
a3f0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
a400: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
a410: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
a420: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
a430: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
a440: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
a450: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
a460: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
a470: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
a480: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
a490: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
a4a0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
a4b0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
a4c0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
a4d0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
a4e0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
a4f0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
a500: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
a510: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
a520: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
a530: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
a540: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
a550: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
a560: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
a570: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a580: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
a590: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
a5a0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a5b0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
a5c0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
a5d0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
a5e0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
a5f0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
a600: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
a610: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
a620: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
a630: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
a640: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a650: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
a660: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
a670: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
a680: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
a690: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
a6a0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
a6b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
a6c0: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
a6d0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
a6e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a6f0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
a700: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
a710: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
a720: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
a730: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
a740: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
a750: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
a760: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a770: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
a780: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
a790: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a7a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
a7b0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
a7c0: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
a7d0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
a7e0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
a7f0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
a800: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
a810: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
a820: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
a830: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
a840: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
a850: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
a860: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
a870: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
a880: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
a890: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
a8a0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
a8b0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
a8c0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
a8d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
a8e0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
a8f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
a900: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
a910: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
a920: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
a930: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
a940: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
a950: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a960: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
a970: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
a980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a990: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
a9a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
a9b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
a9c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
a9d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
a9e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
a9f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
aa00: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
aa10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
aa20: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
aa30: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
aa40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
aa50: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
aa60: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
aa70: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
aa80: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
aa90: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
aaa0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
aab0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
aac0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
aad0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
aae0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
aaf0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
ab00: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
ab10: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
ab20: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
ab30: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
ab40: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
ab50: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
ab60: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
ab70: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
ab80: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
ab90: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
aba0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
abb0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
abc0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
abd0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
abe0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
abf0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
ac00: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
ac10: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
ac20: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
ac30: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
ac40: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
ac50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
ac60: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
ac70: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
ac80: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
ac90: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
aca0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
acb0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
acc0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
acd0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
ace0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
acf0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
ad00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ad10: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
ad20: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
ad30: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
ad40: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
ad50: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
ad60: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
ad70: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
ad80: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
ad90: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
ada0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
adb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
adc0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
add0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
ade0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
adf0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
ae00: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
ae10: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
ae20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
ae30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
ae40: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
ae50: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
ae60: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
ae70: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
ae80: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
ae90: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
aea0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
aeb0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
aec0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
aed0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
aee0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
aef0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
af00: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
af10: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
af20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
af30: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
af40: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
af50: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
af60: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
af70: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
af80: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
af90: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
afa0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
afb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
afc0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
afd0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
afe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
aff0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
b000: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
b010: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
b020: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
b030: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
b040: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
b050: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
b060: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b070: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
b080: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
b090: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
b0a0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
b0b0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
b0c0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
b0d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b0e0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
b0f0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
b100: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
b110: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
b120: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
b130: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
b140: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
b150: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
b160: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
b170: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
b180: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
b190: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
b1a0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
b1b0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
b1c0: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
b1d0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
b1e0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
b1f0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
b200: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
b210: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
b220: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
b230: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
b240: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
b250: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
b260: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
b270: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
b280: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
b290: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
b2a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
b2b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b2c0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
b2d0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
b2e0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
b2f0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
b300: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
b310: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
b320: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
b330: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b340: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
b350: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
b360: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
b370: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
b380: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
b390: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
b3a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
b3b0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
b3c0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
b3d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
b3e0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
b3f0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
b400: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
b410: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
b420: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
b430: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
b440: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
b450: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
b460: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
b470: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
b480: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
b490: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
b4a0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
b4b0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
b4c0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
b4d0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
b4e0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
b4f0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
b500: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
b510: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
b520: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
b530: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
b540: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
b550: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
b560: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
b570: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
b580: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
b590: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
b5a0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
b5b0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
b5c0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
b5d0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
b5e0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
b5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
b600: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
b610: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
b620: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
b630: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
b640: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b650: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
b660: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
b670: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
b680: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
b690: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
b6a0: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
b6b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
b6c0: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
b6d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b6e0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
b6f0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
b700: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
b710: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
b720: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
b730: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
b740: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
b750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
b760: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
b770: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
b780: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
b790: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
b7a0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
b7b0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
b7c0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
b7d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
b7e0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
b7f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
b800: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
b810: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
b820: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
b830: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
b840: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
b850: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
b860: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
b870: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
b880: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
b890: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
b8a0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
b8b0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
b8c0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
b8d0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
b8e0: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
b8f0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
b900: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
b910: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
b920: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
b930: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
b940: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
b950: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
b960: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
b970: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
b980: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
b990: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
b9a0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
b9b0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
b9c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
b9d0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
b9e0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b9f0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ba00: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
ba10: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
ba20: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
ba30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ba40: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
ba50: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
ba60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ba70: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
ba80: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
ba90: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
baa0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bab0: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
bac0: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
bad0: 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65   argument).  The
bae0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  .** sqlite3_db_c
baf0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
bb00: 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65  e should only be
bb10: 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c   used immediatel
bb20: 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64  y after.** the d
bb30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bb40: 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73  on is created us
bb50: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
bb60: 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  n()],.** [sqlite
bb70: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
bb80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
bb90: 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
bba0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
bbb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
bbc0: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
bbd0: 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67  is the.** config
bbe0: 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61  uration verb - a
bbf0: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
bc00: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
bc10: 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20  at.** aspect of 
bc20: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
bc30: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
bc40: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
bc50: 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63  * The only choic
bc60: 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65  e for this value
bc70: 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f   is [SQLITE_DBCO
bc80: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e  NFIG_LOOKASIDE].
bc90: 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72  .** New verbs ar
bca0: 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61  e likely to be a
bcb0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
bcc0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
bcd0: 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  e..** Additional
bce0: 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e   arguments depen
bcf0: 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a  d on the verb..*
bd00: 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
bd10: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
bd20: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
bd30: 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
bd40: 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
bd50: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
bd60: 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
bd70: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
bd80: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
bd90: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
bda0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
bdb0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
bdc0: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
bdd0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
bde0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bdf0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
be00: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
be10: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
be20: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
be30: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
be40: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
be50: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
be60: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
be70: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
be80: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
be90: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
bea0: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
beb0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
bec0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bed0: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
bee0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
bef0: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
bf00: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
bf10: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
bf20: 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
bf30: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
bf40: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
bf50: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
bf60: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
bf70: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
bf80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
bf90: 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
bfa0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
bfb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
bfc0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
bfd0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
bfe0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
bff0: 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
c000: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
c010: 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
c020: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
c030: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
c040: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
c050: 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
c060: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
c070: 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
c080: 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
c090: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
c0a0: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
c0b0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
c0c0: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
c0d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
c0e0: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
c0f0: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
c100: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
c110: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
c120: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
c130: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
c140: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
c150: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
c160: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
c170: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
c180: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
c190: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
c1a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
c1b0: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
c1c0: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
c1d0: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
c1e0: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
c1f0: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
c200: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
c210: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
c220: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
c230: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20  .** The xMalloc 
c240: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
c250: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
c260: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
c270: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
c280: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
c290: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
c2a0: 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c  y..** The xReall
c2b0: 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77  oc method must w
c2c0: 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63  ork like realloc
c2d0: 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  () from the stan
c2e0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a  dard C library.*
c2f0: 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70  * with the excep
c300: 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65  tion that if the
c310: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
c320: 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20   to xRealloc is 
c330: 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  zero,.** xReallo
c340: 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f  c must be a no-o
c350: 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20  p - it must not 
c360: 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f  perform any allo
c370: 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61  cation or.** dea
c380: 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c  llocation.  ^SQL
c390: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
c3a0: 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
c3b0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
c3c0: 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
c3d0: 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
c3e0: 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
c3f0: 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
c400: 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65  * And so in case
c410: 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70  s where xRoundup
c420: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
c430: 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
c440: 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63  r,.** xRealloc c
c450: 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74  an perform exact
c460: 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61  ly as the standa
c470: 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c  rd library reall
c480: 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c  oc() and.** stil
c490: 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e  l be in complian
c4a0: 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65  ce with this spe
c4b0: 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  cification..**.*
c4c0: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
c4d0: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
c4e0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
c4f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
c500: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
c510: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
c520: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
c530: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
c540: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
c550: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
c560: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
c570: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
c580: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
c590: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
c5a0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
c5b0: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
c5c0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
c5d0: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
c5e0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
c5f0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
c600: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
c610: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
c620: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
c630: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c640: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
c650: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
c660: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
c670: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
c680: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
c690: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
c6a0: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
c6b0: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
c6c0: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
c6d0: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
c6e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c6f0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
c700: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
c710: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
c720: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
c730: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
c740: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
c750: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
c760: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c770: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
c780: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
c790: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
c7a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c7b0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
c7c0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
c7d0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
c7e0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
c7f0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
c800: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
c810: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
c820: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
c830: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
c840: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
c850: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
c860: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
c870: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
c880: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
c890: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
c8a0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
c8b0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
c8c0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
c8d0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
c8e0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
c8f0: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
c900: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
c910: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
c920: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
c930: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
c940: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
c950: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
c960: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
c970: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
c980: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
c990: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
c9a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c9b0: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
c9c0: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
c9d0: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
c9e0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
c9f0: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
ca00: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
ca10: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
ca20: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
ca30: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
ca40: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
ca50: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
ca60: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ca70: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
ca80: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
ca90: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
caa0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
cab0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
cac0: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
cad0: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
cae0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
caf0: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
cb00: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
cb10: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
cb20: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
cb30: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
cb40: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
cb50: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
cb60: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
cb70: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
cb80: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
cb90: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
cba0: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
cbb0: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
cbc0: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
cbd0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
cbe0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
cbf0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
cc00: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
cc10: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
cc20: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
cc30: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
cc40: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
cc50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
cc60: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
cc70: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
cc80: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
cc90: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
cca0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
ccb0: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
ccc0: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
ccd0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
cce0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
ccf0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
cd00: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
cd10: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
cd20: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
cd30: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
cd40: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
cd50: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
cd60: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
cd70: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
cd80: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
cd90: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
cda0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
cdb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
cdc0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
cdd0: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
cde0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
cdf0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
ce00: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
ce10: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
ce20: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
ce30: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
ce40: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
ce50: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
ce60: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
ce70: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
ce80: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
ce90: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
cea0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
ceb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
cec0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
ced0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
cee0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
cef0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
cf00: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
cf10: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
cf20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
cf30: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
cf40: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
cf50: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
cf60: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
cf70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cf80: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
cf90: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
cfa0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
cfb0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
cfc0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
cfd0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
cfe0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
cff0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d000: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d010: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d020: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d030: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d040: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d050: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d060: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d070: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d080: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d090: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d0a0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d0b0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d0c0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d0d0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d0e0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d0f0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
d100: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
d110: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
d120: 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
d130: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
d140: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
d150: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
d160: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
d170: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
d180: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
d190: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
d1a0: 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
d1b0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
d1c0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
d1d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d1e0: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
d1f0: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
d200: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
d210: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
d220: 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
d230: 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
d240: 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
d250: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
d260: 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
d270: 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
d280: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
d290: 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
d2a0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
d2b0: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
d2c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
d2d0: 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
d2e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d2f0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
d300: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d310: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
d320: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
d330: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
d340: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
d350: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
d360: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
d370: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
d380: 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
d390: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
d3a0: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
d3b0: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
d3c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
d3d0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
d3e0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
d3f0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
d400: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
d410: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
d420: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
d430: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d440: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
d450: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
d460: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
d470: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
d480: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
d490: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
d4a0: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
d4b0: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
d4c0: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
d4d0: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
d4e0: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
d4f0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
d500: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d510: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
d520: 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
d530: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
d540: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
d550: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
d560: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
d570: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
d580: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
d590: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
d5a0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
d5b0: 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
d5c0: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
d5d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
d5e0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
d5f0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d600: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d610: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
d620: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
d630: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d640: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d650: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d660: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
d670: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
d680: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
d690: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
d6a0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
d6b0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
d6c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
d6d0: 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
d6e0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
d6f0: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
d700: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
d710: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
d720: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
d730: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d740: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d750: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d760: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
d770: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
d780: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
d790: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
d7a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d7b0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
d7c0: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
d7d0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
d7e0: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
d7f0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
d800: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d810: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d820: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
d830: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
d840: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
d850: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
d860: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
d870: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
d880: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
d890: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
d8a0: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
d8b0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
d8c0: 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
d8d0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
d8e0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
d8f0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
d900: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
d910: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
d920: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
d930: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
d940: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
d950: 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
d960: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
d970: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d980: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
d990: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
d9a0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
d9b0: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
d9c0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
d9d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d9e0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
d9f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
da00: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
da10: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
da20: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
da30: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
da40: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
da50: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
da60: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
da70: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
da80: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
da90: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
daa0: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
dab0: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
dac0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
dad0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
dae0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
daf0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
db00: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
db10: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
db20: 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
db30: 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
db40: 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
db50: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
db60: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
db70: 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
db80: 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
db90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
dba0: 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
dbb0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
dbc0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
dbd0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
dbe0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
dbf0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
dc00: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
dc10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
dc20: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
dc30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
dc40: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
dc50: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
dc60: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
dc70: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
dc80: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
dc90: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
dca0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dcb0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
dcc0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
dcd0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
dce0: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
dcf0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
dd00: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
dd10: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
dd20: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
dd30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
dd40: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
dd50: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
dd60: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
dd70: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
dd80: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dd90: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
dda0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
ddb0: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
ddc0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
ddd0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
dde0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
ddf0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
de00: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
de10: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
de20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
de30: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
de40: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
de50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
de60: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
de70: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
de80: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
de90: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
dea0: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
deb0: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
dec0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
ded0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
dee0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
def0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
df00: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
df10: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
df20: 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c  _limit()].**   <
df30: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
df40: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
df50: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
df60: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
df70: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
df80: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
df90: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
dfa0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
dfb0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
dfc0: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
dfd0: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
dfe0: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
dff0: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
e000: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
e010: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
e020: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e030: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
e040: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
e050: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
e060: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
e070: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
e080: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
e090: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
e0a0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
e0b0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
e0c0: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
e0d0: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
e0e0: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
e0f0: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68  which the scrach
e100: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
e110: 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
e120: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
e130: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
e140: 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
e150: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
e160: 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
e170: 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
e180: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
e190: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
e1a0: 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65  tiple of 16. The
e1b0: 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68   sz parameter sh
e1c0: 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79  ould be a few by
e1d0: 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68  tes.** larger th
e1e0: 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63  an the actual sc
e1f0: 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75  ratch space requ
e200: 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74 65  ired due to inte
e210: 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a  rnal overhead..*
e220: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
e230: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
e240: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
e250: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
e260: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
e270: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
e280: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
e290: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
e2a0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
e2b0: 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72 20  atch buffer per 
e2c0: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
e2d0: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
e2e0: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  o the expected m
e2f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
e300: 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c 69   threads.  ^SQLi
e310: 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72  te will.** never
e320: 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
e330: 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
e340: 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 69  s more than 6 ti
e350: 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
e360: 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  .** page size. ^
e370: 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
e380: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
e390: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
e3a0: 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20  beyond .** what 
e3b0: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
e3c0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
e3d0: 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
e3e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
e3f0: 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
e400: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
e410: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
e420: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e430: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e440: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e450: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e460: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
e470: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
e480: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
e490: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
e4a0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
e4b0: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
e4c0: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
e4d0: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20   implemenation. 
e4e0: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
e4f0: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
e500: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
e510: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
e520: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
e530: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e540: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
e550: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e560: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
e570: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
e580: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
e590: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
e5a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
e5b0: 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
e5c0: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
e5d0: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
e5e0: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
e5f0: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
e600: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
e610: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
e620: 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
e630: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
e640: 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
e650: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
e660: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
e670: 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
e680: 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
e690: 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
e6a0: 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
e6b0: 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
e6c0: 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
e6d0: 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
e6e0: 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
e6f0: 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
e700: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
e710: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
e720: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
e730: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
e740: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
e750: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
e760: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
e770: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
e780: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
e790: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
e7a0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
e7b0: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
e7c0: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
e7d0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
e7e0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
e7f0: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
e800: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
e810: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
e820: 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
e830: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
e840: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
e850: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
e860: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
e870: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
e880: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
e890: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e8a0: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
e8b0: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
e8c0: 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d  pace..** ^The im
e8d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e8e0: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f  ht use one or mo
e8f0: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66  re of the N buff
e900: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20  ers to hold .** 
e910: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  memory accountin
e920: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54  g information. T
e930: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
e940: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e950: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
e960: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
e970: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
e980: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
e990: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
e9a0: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
e9b0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
e9d0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
e9e0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
e9f0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
ea00: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
ea10: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
ea20: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
ea30: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
ea40: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
ea50: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
ea60: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
ea70: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
ea80: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
ea90: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
eaa0: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
eab0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
eac0: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
ead0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
eae0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
eaf0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
eb00: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
eb10: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
eb20: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
eb30: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
eb40: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
eb50: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
eb60: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
eb70: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
eb80: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
eb90: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
eba0: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
ebb0: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
ebc0: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
ebd0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
ebe0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
ebf0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
ec00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
ec10: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
ec20: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
ec30: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
ec40: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
ec50: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
ec60: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
ec70: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
ec80: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
ec90: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
eca0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
ecb0: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
ecc0: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
ecd0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
ece0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
ecf0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
ed00: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
ed10: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
ed20: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
ed30: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
ed40: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
ed50: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
ed60: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
ed70: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
ed80: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ed90: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
eda0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
edb0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
edc0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
edd0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
ede0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
edf0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
ee00: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ee10: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ee20: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
ee30: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
ee40: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
ee50: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
ee60: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
ee70: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
ee80: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
ee90: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
eea0: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
eeb0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
eec0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
eed0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
eee0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
eef0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
ef00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ef10: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
ef20: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
ef30: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
ef40: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
ef50: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
ef60: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
ef70: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
ef80: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
ef90: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
efa0: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
efb0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
efc0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
efd0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
efe0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
eff0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f000: 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
f010: 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
f020: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
f030: 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
f040: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f050: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
f060: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f070: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f080: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f090: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f0a0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f0b0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f0c0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
f0d0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
f0e0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
f0f0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f100: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
f110: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
f120: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
f130: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
f140: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
f150: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
f160: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
f170: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
f180: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
f190: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
f1a0: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
f1b0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
f1c0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
f1d0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
f1e0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
f1f0: 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
f200: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f210: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f220: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f230: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f240: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f250: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f260: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
f270: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
f280: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
f290: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
f2a0: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
f2b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f2c0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f2d0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f2e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f2f0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
f300: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
f310: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
f320: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f330: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f340: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f350: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
f360: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
f370: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
f380: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
f390: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
f3a0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
f3b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
f3c0: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
f3d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f3e0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f3f0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
f400: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
f410: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
f420: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
f430: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
f440: 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
f450: 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
f460: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
f470: 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
f480: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
f490: 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
f4a0: 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
f4b0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f4c0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
f4d0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
f4e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
f4f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
f500: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
f510: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
f520: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
f530: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
f540: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f550: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
f560: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
f570: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
f580: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
f590: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
f5a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
f5b0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
f5c0: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
f5d0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
f5e0: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
f5f0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
f600: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
f610: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
f620: 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
f630: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
f640: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
f650: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
f660: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
f670: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
f680: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f690: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
f6a0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
f6b0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f6c0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f6d0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f6e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f6f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
f700: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
f710: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
f720: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
f730: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
f740: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
f750: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
f760: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
f770: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f780: 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
f790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
f7a0: 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
f7b0: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
f7c0: 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
f7d0: 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
f7e0: 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
f7f0: 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
f800: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
f810: 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
f820: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
f830: 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
f840: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
f850: 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
f860: 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
f870: 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
f880: 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
f890: 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
f8a0: 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
f8b0: 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
f8c0: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
f8d0: 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
f8e0: 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
f8f0: 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
f900: 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
f910: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
f920: 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
f930: 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
f940: 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
f950: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
f960: 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
f970: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
f980: 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
f990: 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
f9a0: 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
f9b0: 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
f9c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
f9d0: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
f9e0: 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
f9f0: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
fa00: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
fa10: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
fa20: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
fa30: 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
fa40: 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
fa50: 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
fa60: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
fa70: 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
fa80: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
fa90: 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
faa0: 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
fab0: 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
fac0: 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
fad0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
fae0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
faf0: 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
fb00: 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
fb10: 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
fb20: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
fb30: 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
fb40: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
fb50: 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
fb60: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
fb70: 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
fb80: 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
fb90: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fba0: 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
fbb0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
fbc0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
fbd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
fbe0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
fbf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
fc00: 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
fc10: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
fc20: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
fc30: 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
fc40: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
fc50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
fc60: 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
fc70: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
fc80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
fc90: 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
fca0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
fcb0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
fcc0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fcd0: 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
fce0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
fcf0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
fd00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
fd10: 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
fd20: 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
fd30: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
fd40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
fd50: 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
fd60: 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
fd70: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
fd80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
fd90: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
fda0: 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
fdb0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
fdc0: 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
fdd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
fde0: 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
fdf0: 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
fe00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
fe10: 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
fe20: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
fe30: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
fe40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
fe50: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
fe60: 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
fe70: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
fe80: 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
fe90: 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
fea0: 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
feb0: 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
fec0: 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
fed0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
fee0: 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
fef0: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
ff00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ff10: 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
ff20: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
ff30: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
ff40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ff50: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
ff60: 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
ff70: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
ff80: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
ff90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
ffa0: 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
ffb0: 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
ffc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ffd0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
ffe0: 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
fff0: 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
10000 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10010 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10020 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10030 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10040 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10050 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
10060 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
10080 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10090 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
100a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
100b0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
100c0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
100d0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
100e0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
100f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10100 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
10110 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
10120 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
10130 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
10140 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
10150 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10160 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10170 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10180 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
10190 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
101a0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
101b0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
101c0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
101d0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
101e0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
101f0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
10200 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
10210 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
10220 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
10230 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10240 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
10250 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10260 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
10270 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
10280 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
10290 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
102a0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
102b0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
102c0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
102d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
102e0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
102f0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
10300 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10310 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
10320 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
10330 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
10340 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
10350 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
10360 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
10370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10380 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
10390 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
103a0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
103b0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
103c0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
103d0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
103e0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
103f0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
10400 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10410 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
10420 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
10430 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
10440 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
10450 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
10460 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
10470 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10480 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
10490 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
104a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
104b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
104c0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
104d0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
104e0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
104f0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
10500 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
10510 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
10520 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
10530 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
10540 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
10550 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
10560 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10570 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
10580 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
10590 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
105a0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
105b0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
105c0 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ler.** multiple 
105d0 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a  of 8.  See also:
105e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105f0 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a  LOOKASIDE]</dd>.
10600 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
10610 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
10620 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10630 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
10640 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a  d* int int */...
10650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10660 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
10670 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
10680 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
10690 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
106a0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
106b0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
106c0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
106d0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
106e0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
106f0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
10700 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
10710 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
10720 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
10730 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
10740 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
10750 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
10760 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10770 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
10780 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
10790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107a0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
107b0 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
107c0 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
107d0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
107e0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
107f0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
10800 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
10810 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
10820 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
10830 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
10840 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
10850 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
10860 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
10870 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
10880 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
10890 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
108a0 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
108b0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
108c0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
108d0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
108e0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
108f0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
10900 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
10910 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
10920 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
10930 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
10940 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
10950 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
10960 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
10970 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
10980 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
10990 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
109a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
109b0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
109c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
109d0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
109e0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
109f0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
10a00 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
10a10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
10a20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
10a30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
10a40 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
10a50 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
10a60 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
10a70 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
10a80 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
10a90 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
10aa0 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
10ab0 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
10ac0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
10ad0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
10ae0 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
10af0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10b00 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
10b10 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
10b20 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
10b30 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
10b40 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29   trigger fired.)
10b50 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
10b60 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
10b70 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
10b80 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
10b90 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
10ba0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
10bb0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
10bc0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
10bd0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
10be0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
10bf0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
10c00 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
10c10 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
10c20 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
10c30 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
10c40 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
10c50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
10c60 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
10c70 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
10c80 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
10c90 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
10ca0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
10cb0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
10cc0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
10cd0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
10ce0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
10cf0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
10d00 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
10d10 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
10d20 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
10d30 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
10d40 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
10d50 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
10d60 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
10d70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
10d80 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
10d90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
10da0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
10db0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
10dc0 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
10dd0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
10de0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
10df0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
10e00 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
10e10 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
10e20 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
10e30 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
10e40 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
10e50 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
10e60 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
10e70 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
10e80 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
10e90 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
10ea0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
10eb0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
10ec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
10ed0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
10ee0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10ef0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
10f00 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
10f10 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
10f20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
10f30 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
10f40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10f50 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
10f60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10f70 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
10f80 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
10f90 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
10fa0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
10fb0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
10fc0 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
10fd0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
10fe0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
10ff0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
11000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11010 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
11020 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
11030 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
11040 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
11060 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
11070 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
11080 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
11090 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
110a0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
110b0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
110c0 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
110d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
110e0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
110f0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
11100 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
11110 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
11120 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
11130 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
11140 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
11150 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
11160 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
11170 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
11180 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
11190 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
111a0 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
111b0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
111c0 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
111d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
111e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
111f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
11200 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
11210 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
11220 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
11230 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
11240 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
11250 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
11260 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
11270 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
11280 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
11290 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
112a0 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
112b0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
112c0 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
112d0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
112e0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
112f0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
11300 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
11310 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
11320 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
11330 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
11340 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
11350 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
11360 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
11370 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
11380 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
11390 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
113a0 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
113b0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
113c0 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
113d0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
113e0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
113f0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
11400 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
11410 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
11420 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
11430 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
11440 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
11450 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
11460 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
11470 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
11480 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
11490 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
114a0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
114b0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
114c0 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
114d0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
114e0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
114f0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11500 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
11510 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
11520 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
11530 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
11540 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
11550 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
11560 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
11570 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
11580 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
11590 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
115a0 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
115b0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
115c0 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
115d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
115e0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
115f0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
11600 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
11610 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
11620 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11630 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
11640 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11650 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
11660 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
11670 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
11680 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
11690 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
116a0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
116b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
116c0 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
116d0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
116e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
116f0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
11700 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
11710 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
11720 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
11730 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
11740 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
11750 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
11760 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
11770 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
11780 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
11790 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
117a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
117b0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
117c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
117d0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
117e0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
117f0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
11800 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
11810 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
11820 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
11830 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
11840 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
11850 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
11860 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11870 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
11880 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
11890 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
118a0 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
118b0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
118c0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
118d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
118e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
118f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
11900 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
11910 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
11920 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
11930 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
11940 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
11950 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
11960 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11970 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
11980 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
11990 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
119a0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
119b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
119c0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
119d0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
119e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
119f0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
11a00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11a10 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
11a20 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
11a30 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
11a40 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11a50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11a60 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
11a70 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
11a80 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
11a90 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
11aa0 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
11ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11ac0 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
11ad0 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
11ae0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
11af0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
11b00 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
11b10 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
11b20 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
11b30 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
11b40 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
11b50 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
11b60 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
11b70 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
11b80 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
11b90 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
11ba0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
11bb0 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
11bc0 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
11bd0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
11be0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
11bf0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
11c00 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
11c10 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
11c20 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
11c30 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
11c40 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
11c50 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
11c60 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
11c70 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
11c80 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
11c90 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
11ca0 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
11cb0 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
11cc0 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
11cd0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
11ce0 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
11cf0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
11d00 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
11d10 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
11d20 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
11d30 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
11d40 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
11d50 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
11d60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
11d70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
11d80 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
11d90 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
11da0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
11db0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
11dc0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
11dd0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
11de0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
11df0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
11e00 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
11e10 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
11e20 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
11e30 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
11e40 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
11e50 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
11e60 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
11e70 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
11e80 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
11e90 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
11ea0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
11eb0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
11ec0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11ed0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11ee0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11ef0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
11f00 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
11f10 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
11f20 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
11f30 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
11f40 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
11f50 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
11f60 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
11f70 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
11f80 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
11f90 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
11fa0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
11fb0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
11fc0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
11fd0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
11fe0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
11ff0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
12000 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
12010 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
12020 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
12030 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
12040 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
12050 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
12060 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
12070 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
12080 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
12090 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
120a0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
120b0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
120c0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
120d0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
120e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
120f0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
12100 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
12110 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
12120 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12130 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
12140 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
12150 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
12160 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
12170 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
12180 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
12190 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
121a0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
121b0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
121c0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
121d0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
121e0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
121f0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
12200 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
12210 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
12220 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
12230 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
12240 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
12250 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
12260 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
12270 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
12280 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
12290 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
122a0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
122b0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
122c0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
122d0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
122e0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
122f0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
12300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
12310 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
12320 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
12330 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
12340 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
12350 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
12360 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12370 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
12380 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
12390 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
123a0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
123b0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
123c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
123d0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
123e0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
123f0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
12400 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
12410 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
12420 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
12430 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
12440 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12450 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
12460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
12470 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
12480 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
12490 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
124a0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
124b0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
124c0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
124d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
124e0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
124f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12500 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
12510 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
12520 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
12530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
12540 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
12550 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
12560 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
12570 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
12580 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
12590 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
125a0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
125b0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
125c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
125d0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
125e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
125f0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
12600 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
12610 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
12620 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
12630 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
12640 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12650 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
12660 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
12670 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
12680 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
12690 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
126a0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
126b0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
126c0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
126d0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
126e0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
126f0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
12700 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
12710 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
12720 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
12730 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
12740 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
12750 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
12760 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
12770 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12780 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
12790 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
127a0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
127b0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
127c0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
127d0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
127e0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
127f0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
12800 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
12810 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
12820 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
12830 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
12840 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
12850 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
12860 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
12870 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
12880 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
12890 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
128a0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
128b0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
128c0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
128d0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
128e0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
128f0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
12900 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
12910 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
12920 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
12930 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
12940 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
12950 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
12960 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
12970 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
12980 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
12990 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
129a0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
129b0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
129c0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
129d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
129e0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
129f0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
12a00 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
12a10 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
12a20 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
12a30 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
12a40 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
12a50 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
12a60 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
12a70 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
12a80 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
12a90 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
12aa0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
12ab0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
12ac0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
12ad0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12ae0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
12af0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12b00 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
12b10 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
12b20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12b30 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
12b40 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
12b50 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
12b60 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
12b70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12b80 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
12b90 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
12ba0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
12bb0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
12bc0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
12bd0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
12be0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
12bf0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
12c00 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
12c10 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
12c20 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
12c30 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
12c40 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
12c50 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
12c60 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
12c70 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
12c80 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
12c90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12ca0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
12cb0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
12cc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12cd0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
12ce0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
12cf0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
12d00 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
12d10 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
12d20 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
12d30 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
12d40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
12d50 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
12d60 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
12d70 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
12d80 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
12d90 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
12da0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
12db0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
12dc0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
12dd0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
12de0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
12df0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
12e00 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
12e10 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12e20 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
12e30 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
12e40 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
12e50 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
12e60 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
12e70 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
12e80 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
12e90 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
12ea0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
12eb0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
12ec0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12ed0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
12ee0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
12ef0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
12f00 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
12f10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
12f20 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
12f30 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
12f40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12f50 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
12f60 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
12f70 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
12f80 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
12f90 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
12fa0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
12fb0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
12fc0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
12fd0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
12fe0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
12ff0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
13000 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
13010 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
13020 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
13030 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
13040 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13050 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
13060 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
13070 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
13080 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
13090 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
130a0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
130b0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
130c0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
130d0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
130e0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
130f0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
13100 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
13110 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
13120 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
13130 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
13140 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
13150 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
13160 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
13170 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
13180 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
13190 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
131a0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
131b0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
131c0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
131d0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
131e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
131f0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
13200 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
13210 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
13220 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
13230 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
13240 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
13250 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
13260 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
13270 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
13280 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
13290 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
132a0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
132b0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
132c0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
132d0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
132e0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
132f0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
13300 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
13310 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
13320 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
13330 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
13340 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
13350 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
13360 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
13370 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
13380 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
13390 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
133a0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
133b0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
133c0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
133d0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
133e0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
133f0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
13400 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
13410 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
13420 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
13430 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
13440 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
13450 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
13460 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
13470 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
13480 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
13490 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
134a0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
134b0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
134c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
134d0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
134e0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
134f0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13500 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
13510 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
13520 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
13530 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
13540 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
13550 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
13560 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
13570 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
13580 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
13590 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
135a0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
135b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
135c0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
135d0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
135e0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
135f0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
13600 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
13610 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
13620 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
13630 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
13640 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
13650 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
13660 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
13670 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
13680 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
13690 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
136a0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
136b0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
136c0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
136d0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
136e0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
136f0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
13700 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
13710 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
13720 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
13730 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
13740 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
13750 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
13760 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
13770 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
13780 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
13790 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
137a0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
137b0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
137c0 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
137d0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
137e0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
137f0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
13800 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
13810 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
13820 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
13830 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
13840 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
13850 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
13860 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
13870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
13880 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
13890 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
138a0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
138b0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
138c0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
138d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
138e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
138f0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
13900 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
13910 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
13920 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
13930 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
13940 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
13950 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
13960 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
13970 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
13980 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
13990 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
139a0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
139b0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
139c0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
139d0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
139e0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
139f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13a00 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
13a10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13a20 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
13a30 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13a40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13a50 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
13a60 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
13a70 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
13a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13a90 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
13aa0 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
13ab0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13ac0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
13ad0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
13ae0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
13af0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
13b00 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
13b10 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
13b20 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
13b30 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
13b40 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
13b50 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
13b60 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
13b70 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
13b80 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
13b90 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
13ba0 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
13bb0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
13bc0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
13bd0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
13be0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
13bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
13c00 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
13c10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
13c20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13c30 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
13c40 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
13c50 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
13c60 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
13c70 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
13c80 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
13c90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
13ca0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
13cb0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13cc0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13cd0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
13ce0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13cf0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
13d00 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
13d10 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
13d20 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
13d30 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
13d40 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
13d50 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
13d60 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
13d70 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
13d80 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
13d90 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
13da0 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
13db0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
13dc0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
13dd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13de0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
13df0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
13e00 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
13e10 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
13e20 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
13e30 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
13e40 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
13e50 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
13e60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
13e70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
13e80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
13e90 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
13ea0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
13eb0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
13ec0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
13ed0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
13ee0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
13ef0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
13f00 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
13f10 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
13f20 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
13f30 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
13f40 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
13f50 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
13f60 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
13f70 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
13f80 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
13f90 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
13fa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13fb0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
13fc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
13fd0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
13fe0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
13ff0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
14000 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
14010 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
14020 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
14030 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
14040 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
14050 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
14060 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
14070 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
14080 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
14090 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
140a0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
140b0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
140c0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
140d0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
140e0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
140f0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
14100 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
14110 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
14120 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
14130 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
14140 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
14150 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
14160 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
14170 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
14180 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
14190 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
141a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
141b0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
141c0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
141d0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
141e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
141f0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
14200 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
14210 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
14220 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
14230 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
14240 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
14250 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14260 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
14270 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
14280 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
14290 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
142a0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
142b0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
142c0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
142d0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
142e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
142f0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
14300 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
14310 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
14320 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
14330 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
14340 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14350 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
14360 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
14370 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
14380 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
14390 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
143a0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
143b0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
143c0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
143d0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
143e0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
143f0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
14400 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
14410 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
14420 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14430 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
14440 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
14450 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
14460 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
14470 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
14480 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14490 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
144a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
144b0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
144c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
144d0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
144e0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
144f0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
14500 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
14510 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
14520 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
14530 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14540 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
14550 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14560 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te>.**.** ^The s
14570 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14580 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
14590 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
145a0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
145b0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
145c0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
145d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
145e0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
145f0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
14600 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
14610 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
14620 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
14630 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
14640 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
14650 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
14660 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
14670 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
14680 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
14690 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
146a0 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73  ** it should pas
146b0 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
146c0 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
146d0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
146e0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
146f0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14700 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14710 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14720 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14740 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14750 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14760 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14770 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14780 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14790 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
147a0 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
147b0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
147c0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
147d0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
147e0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
147f0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14800 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
14810 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14820 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
14830 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
14840 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
14850 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
14860 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
14870 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14880 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
14890 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
148a0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
148b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
148c0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
148d0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
148e0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
148f0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
14900 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
14910 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
14920 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
14930 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
14940 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
14950 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
14960 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
14970 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
14980 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
14990 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
149a0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
149b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
149c0 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  )].)^.*/.int sql
149d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
149e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
149f0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
14a00 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
14a10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
14a20 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
14a30 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
14a40 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
14a50 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
14a60 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
14a70 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
14a80 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
14a90 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
14aa0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
14ab0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
14ac0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
14ad0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
14ae0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
14af0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
14b00 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
14b10 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
14b20 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
14b30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
14b40 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
14b50 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
14b60 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
14b70 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
14b80 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
14b90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
14ba0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
14bb0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
14bc0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
14bd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
14be0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
14bf0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
14c00 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
14c10 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
14c20 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
14c30 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
14c40 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
14c50 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
14c60 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
14c70 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
14c80 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
14c90 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
14ca0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
14cb0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
14cc0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
14cd0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
14ce0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
14cf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
14d00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14d10 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
14d20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
14d30 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
14d40 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
14d50 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
14d60 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
14d70 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
14d80 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
14d90 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
14da0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
14db0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
14dc0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
14dd0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
14de0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
14df0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14e00 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
14e10 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
14e20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14e30 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
14e40 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
14e50 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
14e60 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
14e70 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
14e80 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
14e90 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
14ea0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
14eb0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
14ec0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
14ed0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14ee0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
14ef0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
14f00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
14f10 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
14f20 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
14f30 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
14f40 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
14f50 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
14f60 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
14f70 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
14f80 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
14f90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
14fa0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
14fb0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
14fc0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
14fd0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
14fe0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
14ff0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
15000 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
15010 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
15020 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
15030 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
15040 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
15050 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
15060 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
15070 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
15080 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
15090 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
150a0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
150b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
150c0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
150d0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
150e0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
150f0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
15100 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
15110 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
15120 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
15130 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
15140 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
15150 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
15160 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
15170 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
15180 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
15190 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
151a0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
151b0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
151c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
151d0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
151e0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
151f0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
15200 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
15210 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
15220 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
15230 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
15240 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
15250 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
15260 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
15270 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
15280 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
15290 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
152a0 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
152b0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
152c0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
152d0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
152e0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
152f0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
15300 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
15310 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
15320 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
15330 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
15340 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
15350 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
15360 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
15370 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
15380 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
15390 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
153a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
153b0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
153c0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
153d0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
153e0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
153f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15400 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15410 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
15420 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
15430 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
15440 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15450 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
15460 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
15470 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
15480 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15490 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
154a0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
154b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
154c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
154d0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
154e0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
154f0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
15500 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
15510 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
15520 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
15530 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15540 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
15550 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
15560 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
15570 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
15580 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
15590 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
155a0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
155b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
155c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
155d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
155e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
155f0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
15600 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
15610 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15620 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
15630 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
15640 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
15650 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
15660 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
15670 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
15680 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15690 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
156a0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
156b0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
156c0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
156d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
156e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
156f0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
15700 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
15710 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
15720 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
15730 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
15740 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
15750 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
15760 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
15770 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
15780 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
15790 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
157a0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
157b0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
157c0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
157d0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
157e0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
157f0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
15800 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
15810 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
15820 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
15830 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
15840 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
15850 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
15860 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
15870 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
15880 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
15890 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
158a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
158b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
158c0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
158d0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
158e0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
158f0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
15900 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
15910 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
15920 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
15930 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
15940 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15950 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
15960 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
15970 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
15980 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
15990 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
159a0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
159b0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
159c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
159d0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
159e0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
159f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
15a00 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
15a10 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
15a20 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
15a30 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
15a40 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
15a50 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
15a60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
15a70 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
15a80 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
15a90 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
15aa0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
15ab0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
15ac0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
15ad0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
15ae0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
15af0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
15b00 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
15b10 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
15b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
15b30 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
15b40 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
15b50 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
15b60 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
15b70 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
15b80 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
15b90 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
15ba0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15bb0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
15bc0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
15bd0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
15be0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
15bf0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
15c00 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
15c10 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
15c20 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
15c30 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
15c40 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
15c50 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
15c60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
15c70 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
15c80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
15c90 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
15ca0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
15cb0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
15cc0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
15cd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
15ce0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
15cf0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
15d00 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
15d10 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
15d20 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
15d30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15d40 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
15d50 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
15d60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
15d70 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
15d80 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
15d90 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
15da0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
15db0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
15dc0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
15dd0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
15de0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
15df0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
15e00 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
15e10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15e20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
15e30 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
15e40 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
15e50 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
15e60 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
15e70 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
15e80 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
15e90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
15ea0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
15eb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
15ec0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
15ed0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
15ee0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
15ef0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
15f00 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
15f10 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
15f20 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
15f30 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
15f40 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
15f50 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
15f60 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
15f70 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
15f80 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
15f90 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
15fa0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
15fb0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
15fc0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
15fd0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
15fe0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
15ff0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
16000 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
16010 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
16020 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
16030 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
16040 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
16050 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
16060 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
16070 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
16080 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
16090 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
160a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
160b0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
160c0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
160d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
160e0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
160f0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
16100 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
16110 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
16120 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
16130 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
16140 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16150 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
16160 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
16170 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
16180 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
16190 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
161a0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
161b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
161c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
161d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
161e0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
161f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
16200 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
16210 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
16220 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
16230 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
16240 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
16250 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
16260 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
16270 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
16280 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16290 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
162a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
162b0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
162c0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
162d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
162e0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
162f0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
16300 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
16310 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
16320 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
16330 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
16340 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16350 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
16360 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
16370 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16380 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
16390 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
163a0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
163b0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
163c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
163d0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
163e0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
163f0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
16400 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
16410 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
16420 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16430 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
16440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
16450 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
16460 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
16480 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
16490 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
164a0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
164b0 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a  e boundary..**.*
164c0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
164d0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
164e0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
164f0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
16500 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
16510 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
16520 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
16530 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
16540 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
16550 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
16560 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
16570 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
16580 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
16590 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
165a0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
165b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
165c0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
165d0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
165e0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
165f0 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
16600 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
16610 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
16620 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
16630 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
16640 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
16650 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
16660 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
16670 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
16680 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
16690 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
166a0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
166b0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
166c0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
166d0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
166e0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
166f0 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
16700 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
16710 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
16720 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
16730 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
16740 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
16750 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
16760 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
16770 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
16780 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16790 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
167a0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
167b0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
167c0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
167d0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
167e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
167f0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
16800 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
16810 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
16820 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
16830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
16840 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16850 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
16860 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
16870 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
16880 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
16890 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
168a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
168b0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
168c0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
168d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
168e0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
168f0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
16900 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
16910 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
16920 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
16930 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
16940 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
16950 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
16960 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
16970 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
16980 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
16990 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
169a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
169b0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
169c0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
169d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
169e0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
169f0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
16a00 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
16a10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
16a20 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
16a30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16a40 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
16a50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16a60 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
16a70 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
16a80 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
16a90 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
16aa0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
16ab0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
16ac0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
16ad0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
16ae0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
16af0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
16b00 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
16b10 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
16b20 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
16b30 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
16b40 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
16b50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
16b60 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
16b70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
16b80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
16b90 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
16ba0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
16bb0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
16bc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
16bd0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
16be0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
16bf0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
16c00 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
16c10 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
16c20 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
16c30 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
16c40 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
16c50 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
16c60 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
16c70 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
16c80 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
16c90 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
16ca0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
16cb0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
16cc0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
16cd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
16ce0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
16cf0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
16d00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
16d10 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
16d20 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
16d30 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
16d40 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
16d50 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
16d60 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16d70 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
16d80 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
16d90 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16da0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16db0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
16dc0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
16dd0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
16de0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
16df0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
16e00 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
16e10 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
16e20 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
16e30 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
16e40 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
16e50 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
16e60 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
16e70 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
16e80 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
16e90 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
16ea0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
16eb0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
16ec0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
16ed0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
16ee0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
16ef0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
16f00 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
16f10 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
16f20 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
16f30 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
16f40 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
16f50 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
16f60 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
16f70 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
16f80 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
16f90 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
16fa0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
16fb0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
16fc0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
16fd0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
16fe0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
16ff0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
17000 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
17010 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
17020 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
17030 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
17040 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
17050 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
17060 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
17070 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
17080 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
17090 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
170a0 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
170b0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
170c0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
170d0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
170e0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
170f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
17100 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
17110 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
17120 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
17130 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
17140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17150 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
17160 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
17170 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
17180 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
17190 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
171a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
171b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
171c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
171d0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
171e0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
171f0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
17200 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17210 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
17220 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
17230 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
17240 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
17250 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
17260 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
17270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17280 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
17290 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
172a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
172b0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
172c0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
172d0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
172e0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
172f0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
17300 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
17310 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
17320 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
17330 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17340 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
17350 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
17360 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
17370 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
17380 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17390 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
173a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
173b0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
173c0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
173d0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
173e0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
173f0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
17400 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17410 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
17420 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
17430 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
17440 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
17450 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
17460 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
17470 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
17480 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
17490 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
174a0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
174b0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
174c0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
174d0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
174e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
174f0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
17500 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17510 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
17520 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
17530 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
17540 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
17550 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
17560 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
17570 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
17580 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
17590 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
175a0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
175b0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
175c0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
175d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
175e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
175f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
17600 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
17610 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
17620 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
17630 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
17640 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
17650 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
17660 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
17670 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
17680 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
17690 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
176a0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
176b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
176c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
176d0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
176e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
176f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17700 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
17710 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17720 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
17730 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
17740 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
17750 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
17760 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
17770 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
17780 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
17790 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
177a0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
177b0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
177c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
177d0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
177e0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
177f0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
17800 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
17810 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
17820 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17830 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
17840 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
17850 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
17860 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
17870 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17880 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
17890 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
178a0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
178b0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
178c0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
178d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
178e0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
178f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
17900 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
17910 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
17920 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
17930 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
17940 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
17950 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
17960 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
17970 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
17980 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
17990 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
179a0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
179b0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
179c0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
179d0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
179e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
179f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
17a00 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
17a10 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
17a20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
17a30 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
17a40 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
17a50 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
17a60 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
17a70 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
17a80 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
17a90 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
17aa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17ab0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
17ac0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17ad0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
17ae0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
17af0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
17b00 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
17b10 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
17b20 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
17b30 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
17b40 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
17b50 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
17b60 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
17b70 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
17b80 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
17b90 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
17ba0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
17bb0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
17bc0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
17bd0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
17be0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
17bf0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
17c00 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
17c10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
17c20 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
17c30 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
17c40 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
17c50 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
17c60 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
17c70 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
17c80 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
17c90 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
17ca0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
17cb0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
17cc0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
17cd0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
17ce0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
17cf0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
17d00 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
17d10 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
17d20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
17d30 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
17d40 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
17d50 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
17d60 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
17d70 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
17d80 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
17d90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
17da0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
17db0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
17dc0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
17dd0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
17de0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
17df0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
17e00 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
17e10 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
17e20 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
17e30 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
17e40 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
17e50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
17e60 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
17e70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
17e80 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
17e90 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
17ea0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
17eb0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
17ec0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
17ed0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
17ee0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
17ef0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
17f00 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
17f10 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
17f20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
17f30 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
17f40 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
17f50 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
17f60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17f70 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17f80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17f90 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
17fa0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
17fb0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
17fc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
17fd0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
17fe0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
17ff0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
18000 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
18010 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
18020 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
18030 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
18040 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
18050 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
18060 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
18070 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
18080 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
18090 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
180a0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
180b0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
180c0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
180d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
180e0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
180f0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
18100 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18110 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
18120 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
18130 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
18140 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
18150 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18160 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18170 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
18180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18190 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
181a0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
181b0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
181c0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
181d0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
181e0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
181f0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
18200 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
18210 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
18220 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
18230 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
18240 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
18250 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
18260 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
18270 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
18280 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
18290 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
182a0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
182b0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
182c0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
182d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
182e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
182f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
18300 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
18310 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
18320 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
18330 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
18340 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18350 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18360 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18370 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
18380 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
18390 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
183a0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
183b0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
183c0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
183d0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
183e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
183f0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
18400 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
18410 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18420 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
18430 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
18440 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
18450 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
18460 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
18470 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
18480 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
18490 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
184a0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
184b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
184c0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
184d0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
184e0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
184f0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
18500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
18510 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
18520 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
18530 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18540 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
18550 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
18560 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18570 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
18580 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
18590 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
185a0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
185b0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
185c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
185d0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
185e0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
185f0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
18600 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
18610 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
18620 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
18630 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
18640 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
18650 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18660 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
18670 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
18680 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
18690 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
186a0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
186b0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
186c0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
186d0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
186e0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
186f0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
18700 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18710 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
18720 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
18730 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
18740 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
18750 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18760 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18770 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
18780 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
18790 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
187a0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
187b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
187c0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
187d0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
187e0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
187f0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
18800 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
18810 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
18820 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18830 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18840 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18850 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18860 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
18870 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
18880 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
18890 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
188a0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
188b0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
188c0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
188d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
188e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
188f0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
18900 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
18910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18920 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
18930 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
18940 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18950 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18970 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
18980 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
18990 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
189a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
189b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
189c0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
189d0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
189e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
189f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18a10 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
18a20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
18a30 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18a40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18a50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18a60 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
18a70 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
18a80 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18a90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18ab0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
18ac0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
18ad0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18ae0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18af0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18b00 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
18b10 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
18b20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18b30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18b40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18b50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
18b60 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
18b70 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18b80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18b90 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
18ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
18bb0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18bc0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18bd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18be0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
18bf0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
18c00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18c10 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
18c20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18c30 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
18c40 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
18c50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18c60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18c70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18c80 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
18c90 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
18ca0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18cb0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18cc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18cd0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
18ce0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
18cf0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18d00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18d10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18d20 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
18d30 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
18d40 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18d50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18d60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18d70 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
18d80 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
18d90 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18da0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18dc0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
18dd0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
18de0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
18df0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18e00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e10 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
18e20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
18e30 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
18e40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e60 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
18e70 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
18e80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18e90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
18eb0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
18ec0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
18ed0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
18ee0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
18ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
18f00 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
18f10 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
18f20 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
18f30 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
18f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
18f50 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
18f60 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
18f70 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
18f80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
18fa0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
18fb0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
18fc0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
18fd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
18ff0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
19000 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
19010 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19020 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19030 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
19040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19050 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
19060 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19070 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19080 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
19090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
190a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
190b0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
190c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
190d0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
190e0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
190f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
19100 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
19110 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19120 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
19130 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
19140 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19150 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19160 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19170 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
19180 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
19190 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
191a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
191b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
191c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
191d0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
191e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
191f0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
19200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19210 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
19220 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
19230 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19240 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19260 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
19270 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
19280 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19290 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
192a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
192b0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
192c0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
192d0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
192e0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
192f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19300 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
19310 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
19320 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
19330 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19340 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
19350 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
19360 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19370 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
19380 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19390 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
193a0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
193b0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
193c0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
193d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
193e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
193f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
19400 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19410 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
19420 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
19430 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
19440 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19450 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
19460 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19470 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
19480 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
19490 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
194a0 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
194b0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
194c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
194d0 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
194e0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
194f0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
19500 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
19510 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
19520 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
19530 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
19540 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
19550 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
19560 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
19570 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
19580 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
19590 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
195a0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
195b0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
195c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
195d0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
195e0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
195f0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
19600 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
19610 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19620 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
19630 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
19640 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
19650 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
19660 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
19670 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
19680 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
19690 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
196a0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
196b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
196c0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
196d0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
196e0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
196f0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
19700 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
19710 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
19720 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
19730 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
19740 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
19750 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
19760 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
19770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
19780 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
19790 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
197a0 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
197b0 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
197c0 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
197d0 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
197e0 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
197f0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
19800 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
19810 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
19820 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
19830 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
19840 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
19850 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19860 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
19870 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
19880 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
19890 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
198a0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
198b0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
198c0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
198d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
198e0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
198f0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
19900 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
19910 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
19920 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
19930 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
19940 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
19950 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
19960 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
19970 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
19980 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
19990 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
199a0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
199b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
199c0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
199d0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
199e0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
199f0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
19a00 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
19a10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
19a20 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
19a30 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
19a40 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
19a50 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
19a60 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
19a70 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
19a80 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
19a90 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
19aa0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
19ab0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
19ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19ad0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
19ae0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
19af0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
19b00 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
19b10 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
19b20 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
19b30 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
19b40 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
19b50 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
19b60 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
19b70 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
19b80 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
19b90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
19ba0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
19bb0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
19bc0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
19bd0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
19be0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
19bf0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
19c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
19c10 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
19c20 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
19c30 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
19c40 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
19c50 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
19c60 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
19c70 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
19c80 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
19c90 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
19ca0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
19cb0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
19cc0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
19cd0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
19ce0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
19cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
19d00 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
19d10 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
19d20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
19d30 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
19d40 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
19d50 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
19d60 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
19d70 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
19d80 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
19d90 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
19da0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
19db0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
19dc0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
19dd0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
19de0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
19df0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
19e00 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
19e10 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
19e20 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
19e30 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
19e40 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
19e50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
19e60 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
19e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
19e80 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
19e90 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
19ea0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
19eb0 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
19ec0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
19ed0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19ee0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
19ef0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
19f00 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
19f10 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
19f20 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
19f30 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
19f40 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
19f50 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
19f60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19f70 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
19f80 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
19f90 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
19fa0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
19fb0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
19fc0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
19fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19fe0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
19ff0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1a000 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1a010 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1a020 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1a030 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1a040 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1a050 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1a060 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1a070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a080 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
1a090 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
1a0a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a0b0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
1a0c0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
1a0d0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
1a0e0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1a0f0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
1a100 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1a110 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1a120 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1a130 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a140 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61  AREDCACHE],.** a
1a150 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1a160 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1a170 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1a180 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1a190 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1a1a0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1a1b0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a1c0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1a1d0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1a1e0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a1f0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1a200 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a210 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a220 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1a230 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a240 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1a250 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1a260 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1a270 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1a280 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1a290 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1a2a0 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1a2b0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1a2c0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1a2d0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1a2e0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1a2f0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1a300 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1a310 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1a320 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1a330 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1a340 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1a350 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1a360 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1a370 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a380 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1a390 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1a3a0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1a3b0 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1a3c0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1a3d0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1a3e0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1a3f0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1a400 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1a410 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1a420 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1a430 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
1a440 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1a450 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1a460 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1a470 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1a480 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1a490 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1a4a0 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
1a4b0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1a4c0 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
1a4d0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
1a4e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1a4f0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1a500 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a  EN_FULLMUTEX],.*
1a510 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  * [SQLITE_OPEN_S
1a520 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f  HAREDCACHE] and/
1a530 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1a540 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1a550 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  gs,.** then the 
1a560 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1a570 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1a580 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1a590 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1a5a0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1a5b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a5c0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1a5d0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1a5e0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1a5f0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1a600 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1a610 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1a620 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1a630 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1a640 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1a650 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1a660 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1a670 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1a680 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a690 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1a6a0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1a6b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1a6c0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1a6d0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1a6e0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1a6f0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1a700 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1a710 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1a720 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1a730 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1a740 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a750 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1a760 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1a770 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1a780 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1a790 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1a7a0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1a7b0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1a7c0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1a7d0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1a7e0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1a7f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1a800 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1a810 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1a820 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1a830 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1a840 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1a850 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1a860 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1a870 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1a880 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1a890 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1a8a0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1a8b0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1a8c0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1a8d0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1a8e0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1a8f0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1a900 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1a910 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1a920 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1a930 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1a940 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1a950 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1a960 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1a970 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1a980 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1a990 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1a9a0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1a9b0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1a9c0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1a9d0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1a9e0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1a9f0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1aa00 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1aa10 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1aa20 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1aa30 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1aa40 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1aa50 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1aa60 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1aa70 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1aa80 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1aa90 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1aaa0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1aab0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1aac0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1aad0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1aae0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1aaf0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1ab00 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1ab10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1ab20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  closed..**.** ^T
1ab30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1ab40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1ab50 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1ab60 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1ab70 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1ab80 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1ab90 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1aba0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1abb0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1abc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1abd0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1abe0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1abf0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1ac00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1ac10 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1ac20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1ac30 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1ac40 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1ac50 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1ac60 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1ac70 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1ac80 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1ac90 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1aca0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1acb0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1acc0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1acd0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1ace0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1acf0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1ad00 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1ad10 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1ad20 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1ad30 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1ad40 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1ad50 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1ad60 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1ad70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1ad80 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73  n_v2()..*/.int s
1ad90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
1ada0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1adb0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1adc0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1add0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1ade0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1adf0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1ae00 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1ae10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1ae20 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1ae30 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1ae40 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1ae50 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1ae60 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1ae70 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1ae80 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1ae90 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1aea0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1aeb0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1aec0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1aed0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1aee0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1aef0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1af00 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1af10 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1af20 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1af30 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1af40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1af50 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1af60 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1af70 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1af80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1af90 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
1afa0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
1afb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1afc0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1afd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1afe0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1aff0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1b000 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1b010 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1b020 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1b030 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1b040 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b050 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1b060 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1b070 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1b080 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1b090 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1b0a0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1b0b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1b0c0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1b0d0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1b0e0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
1b0f0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1b100 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
1b110 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
1b120 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
1b130 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
1b140 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
1b150 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1b160 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
1b170 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
1b180 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
1b190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b1a0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1b1b0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1b1c0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1b1d0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1b1e0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1b1f0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1b200 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1b210 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1b220 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
1b230 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
1b240 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
1b250 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
1b260 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
1b270 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1b280 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
1b290 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
1b2a0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
1b2b0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
1b2c0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
1b2d0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
1b2e0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
1b2f0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
1b300 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
1b310 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
1b320 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
1b330 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
1b340 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1b350 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
1b360 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
1b370 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
1b380 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
1b390 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
1b3a0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
1b3b0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
1b3c0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
1b3d0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
1b3e0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
1b3f0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
1b400 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
1b410 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
1b420 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
1b430 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
1b440 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
1b450 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
1b460 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
1b470 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
1b480 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
1b490 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
1b4a0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
1b4b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b4c0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
1b4d0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1b4e0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
1b4f0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1b500 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
1b510 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
1b520 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
1b530 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
1b540 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1b550 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
1b560 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
1b570 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
1b580 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
1b590 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
1b5a0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1b5b0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1b5c0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1b5d0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1b5e0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1b5f0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1b600 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1b610 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1b620 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1b630 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1b640 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1b650 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1b660 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1b670 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
1b680 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1b690 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b6a0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1b6b0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1b6c0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1b6d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1b6e0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1b6f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b700 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1b710 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
1b720 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
1b730 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
1b740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
1b750 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
1b760 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
1b770 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
1b780 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
1b790 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
1b7a0 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
1b7b0 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
1b7c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
1b7d0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
1b7e0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1b7f0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
1b800 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
1b810 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
1b820 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
1b830 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
1b840 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
1b850 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
1b860 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
1b870 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b880 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1b890 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
1b8a0 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
1b8b0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
1b8c0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
1b8d0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
1b8e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1b8f0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
1b900 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
1b910 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
1b920 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
1b930 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
1b940 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1b950 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
1b960 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1b970 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
1b980 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
1b990 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
1b9a0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
1b9b0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1b9c0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
1b9d0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1b9e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
1b9f0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1ba00 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
1ba10 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
1ba20 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
1ba30 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
1ba40 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1ba50 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1ba60 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
1ba70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
1ba80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ba90 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
1baa0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
1bab0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1bac0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1bad0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1bae0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1baf0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1bb00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1bb10 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1bb20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1bb30 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1bb40 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1bb50 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1bb60 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1bb70 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1bb80 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1bb90 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1bba0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1bbb0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1bbc0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1bbd0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1bbe0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1bbf0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1bc00 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1bc10 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68  t construct.  Th
1bc20 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
1bc30 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74  ns the old limit
1bc40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
1bc50 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1bc60 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1bc70 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1bc80 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
1bc90 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
1bca0 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
1bcb0 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
1bcc0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1bcd0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1bce0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61  und].** set by a
1bcf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
1bd00 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1bd10 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69  ro named .** [li
1bd20 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
1bd30 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20  X_XYZ]..** (The 
1bd40 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1bd50 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1bd60 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
1bd70 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
1bd80 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1bd90 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1bda0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1bdb0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1bdc0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1bdd0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
1bde0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
1bdf0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1be00 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1be10 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1be20 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1be30 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1be40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1be50 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1be60 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1be70 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1be80 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1be90 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1bea0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1beb0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
1bec0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1bed0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1bee0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1bef0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1bf00 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1bf10 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1bf20 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1bf30 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1bf40 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1bf50 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1bf60 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1bf70 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1bf80 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1bf90 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1bfa0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1bfb0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1bfc0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1bfd0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1bfe0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1bff0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1c000 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1c010 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1c020 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1c030 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1c040 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1c050 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1c060 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1c070 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1c080 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1c090 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1c0a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1c0b0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1c0c0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1c0d0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1c0e0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1c0f0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1c100 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1c110 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1c120 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1c130 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1c140 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1c150 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1c160 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1c170 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1c180 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1c190 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
1c1a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
1c1b0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
1c1c0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1c1d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
1c1e0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1c1f0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
1c200 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
1c210 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
1c220 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
1c230 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1c240 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
1c250 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
1c260 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1c270 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
1c280 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
1c290 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1c2a0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
1c2b0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
1c2c0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
1c2d0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
1c2e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c2f0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1c300 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c310 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1c320 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1c330 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e  table row.<dd>)^
1c340 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c350 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1c360 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1c370 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1c380 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
1c390 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
1c3a0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1c3b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c3c0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1c3d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c3e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1c3f0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1c400 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1c410 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1c420 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1c430 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1c440 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1c450 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1c460 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1c470 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1c480 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
1c490 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1c4a0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1c4b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c4c0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1c4d0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1c4e0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1c4f0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1c500 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c510 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1c520 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1c530 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c540 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1c550 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1c560 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1c570 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1c580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1c590 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1c5a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c5b0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1c5c0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1c5d0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1c5e0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1c5f0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1c600 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1c610 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c620 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1c630 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1c640 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c650 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1c660 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1c670 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c680 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1c690 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1c6a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c6b0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
1c6c0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
1c6d0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
1c6e0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c6f0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1c700 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
1c710 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c720 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
1c730 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
1c740 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
1c750 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
1c760 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
1c770 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c780 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1c790 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
1c7a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c7b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
1c7c0 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
1c7d0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
1c7e0 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
1c7f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c800 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c810 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
1c820 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c830 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
1c840 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
1c850 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
1c860 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1c870 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1c880 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1c890 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1c8a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c8b0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1c8c0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1c8d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c8e0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1c8f0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1c900 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c910 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1c920 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1c930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c940 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1c950 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1c960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c970 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1c980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1c990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c9a0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1c9b0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1c9c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c9d0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1c9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c9f0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1ca00 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1ca10 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1ca20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1ca30 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1ca40 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1ca50 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
1ca60 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1ca70 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1ca80 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
1ca90 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1caa0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1cab0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
1cac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1cad0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
1cae0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
1caf0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
1cb00 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
1cb10 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
1cb20 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
1cb30 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
1cb40 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
1cb50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1cb60 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
1cb70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cb80 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
1cb90 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
1cba0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1cbb0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1cbc0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
1cbd0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
1cbe0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
1cbf0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
1cc00 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
1cc10 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
1cc20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
1cc30 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
1cc40 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
1cc50 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1cc60 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
1cc70 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
1cc80 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
1cc90 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1cca0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
1ccb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
1ccc0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
1ccd0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
1cce0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
1ccf0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1cd00 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
1cd10 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
1cd20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1cd30 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1cd40 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1cd50 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1cd60 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1cd70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
1cd80 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1cd90 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1cda0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1cdb0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1cdc0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1cdd0 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
1cde0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1cdf0 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
1ce00 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
1ce10 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
1ce20 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
1ce30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
1ce40 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
1ce50 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
1ce60 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
1ce70 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
1ce80 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
1ce90 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
1cea0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
1ceb0 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
1cec0 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
1ced0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
1cee0 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
1cef0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
1cf00 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
1cf10 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
1cf20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1cf30 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
1cf40 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
1cf50 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
1cf60 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
1cf70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  s..**.** ^If pzT
1cf80 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
1cf90 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
1cfa0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
1cfb0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
1cfc0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
1cfd0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1cfe0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1cff0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
1d000 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
1d010 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
1d020 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
1d030 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
1d040 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
1d050 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
1d060 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
1d070 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
1d080 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
1d090 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
1d0a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1d0b0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
1d0c0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
1d0d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
1d0e0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
1d0f0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1d100 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1d110 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
1d120 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1d130 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1d140 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1d150 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1d160 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1d170 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1d180 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
1d190 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1d1a0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1d1b0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1d1c0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1d1d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1d1e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1d1f0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1d200 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1d210 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
1d220 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
1d230 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
1d240 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
1d250 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
1d260 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1d270 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
1d280 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
1d290 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1d2a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1d2b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d2c0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1d2d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1d2e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1d2f0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1d300 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1d310 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1d320 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1d330 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1d340 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1d350 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1d360 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1d370 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
1d380 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1d390 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
1d3a0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
1d3b0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
1d3c0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
1d3d0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
1d3e0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
1d3f0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
1d400 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
1d410 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
1d420 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
1d430 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
1d440 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
1d450 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
1d460 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
1d470 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
1d480 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1d490 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
1d4a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
1d4b0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
1d4c0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
1d4d0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
1d4e0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
1d4f0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1d500 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
1d510 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
1d520 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
1d530 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61 20   ^If the schema 
1d540 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
1d550 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
1d560 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
1d570 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
1d580 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1d590 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
1d5a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1d5b0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
1d5c0 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
1d5d0 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
1d5e0 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
1d5f0 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
1d600 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
1d610 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d620 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
1d630 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
1d640 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
1d650 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
1d660 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
1d670 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
1d680 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
1d690 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
1d6a0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
1d6b0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
1d6c0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1d6d0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1d6e0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1d6f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d700 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1d710 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1d720 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1d730 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1d740 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1d750 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1d760 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1d770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1d780 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1d790 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1d7a0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1d7b0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1d7c0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1d7d0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1d7e0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1d7f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1d800 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1d810 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1d820 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1d830 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1d840 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1d850 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1d860 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1d870 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1d880 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1d890 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1d8a0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1d8b0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
1d8c0 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72   of a [parameter
1d8d0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
1d8e0 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20  r] in the WHERE 
1d8f0 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20  clause might.** 
1d900 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 79  change the query
1d910 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
1d920 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  ement, then the 
1d930 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65  statement may be
1d940 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1d950 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73  y recompiled (as
1d960 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
1d970 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  en a schema chan
1d980 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge) on the first
1d990 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
1d9a0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
1d9b0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20  wing any change 
1d9c0 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  to the .** [sqli
1d9d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1d9e0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65  bindings] of the
1d9f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
1da00 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1da10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1da20 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1da30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1da40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1da50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1da60 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1da70 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1da80 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1da90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1daa0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1dab0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1dac0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1dad0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1dae0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1daf0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1db00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1db10 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1db20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1db30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1db40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1db50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1db60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1db70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1db80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1db90 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1dba0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1dbb0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1dbc0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1dbd0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1dbe0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1dbf0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1dc00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1dc10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1dc20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1dc30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1dc40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1dc50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1dc60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1dc70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1dc80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1dc90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1dca0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dcb0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1dcc0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1dcd0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1dce0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1dcf0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1dd00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1dd10 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1dd20 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1dd30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1dd40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1dd50 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1dd60 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1dd70 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1dd80 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1dd90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1dda0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1ddb0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1ddc0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1ddd0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1dde0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1ddf0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1de00 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1de10 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1de20 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1de30 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1de40 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1de50 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1de60 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1de70 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1de80 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1de90 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1dea0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1deb0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1dec0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1ded0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1dee0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1def0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1df00 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1df10 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1df20 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1df30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
1df40 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1df50 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
1df60 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1df70 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1df80 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1df90 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1dfa0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1dfb0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1dfc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dfd0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1dfe0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1dff0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1e000 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1e010 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1e020 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e030 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
1e040 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1e050 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1e060 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1e070 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
1e080 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
1e090 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1e0a0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1e0b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1e0c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1e0d0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1e0e0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1e0f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e100 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
1e110 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
1e120 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
1e130 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
1e140 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
1e150 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1e160 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
1e170 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
1e180 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
1e190 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1e1a0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
1e1b0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1e1c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1e1d0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1e1e0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1e1f0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1e200 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1e210 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1e220 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1e230 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1e240 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1e250 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1e260 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1e270 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1e280 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1e290 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1e2a0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1e2b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e2c0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1e2d0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1e2e0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1e2f0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1e300 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
1e310 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1e320 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1e330 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1e340 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1e350 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1e360 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1e370 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1e380 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1e390 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1e3a0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1e3b0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1e3c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1e3d0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1e3e0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1e3f0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1e400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1e410 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1e420 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1e430 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1e440 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1e450 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1e460 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
1e470 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1e480 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
1e490 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
1e4a0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
1e4b0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
1e4c0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
1e4d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
1e4e0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
1e4f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1e500 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
1e510 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
1e520 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1e530 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1e540 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e550 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e560 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
1e570 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
1e580 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
1e590 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
1e5a0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
1e5b0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
1e5c0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1e5d0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
1e5e0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
1e5f0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74  tion between bet
1e600 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1e610 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1e620 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1e630 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
1e640 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
1e650 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
1e660 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1e670 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
1e680 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
1e690 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
1e6a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1e6b0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
1e6c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1e6d0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
1e6e0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
1e6f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e700 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
1e710 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
1e720 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
1e730 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
1e740 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
1e750 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e760 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
1e770 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
1e780 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
1e790 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1e7a0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
1e7b0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1e7c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
1e7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
1e7e0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
1e7f0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1e800 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1e810 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e820 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1e830 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1e840 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1e850 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
1e860 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
1e870 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
1e880 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
1e890 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
1e8a0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
1e8b0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
1e8c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
1e8d0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
1e8e0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
1e8f0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
1e900 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
1e910 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
1e920 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1e930 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1e940 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
1e950 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1e960 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
1e970 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
1e980 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
1e990 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
1e9a0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
1e9b0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
1e9c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
1e9d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e9e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1e9f0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
1ea00 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
1ea10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1ea20 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
1ea30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1ea40 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
1ea50 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
1ea60 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
1ea70 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1ea80 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1ea90 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1eaa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
1eab0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
1eac0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1ead0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
1eae0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
1eaf0 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
1eb00 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
1eb10 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
1eb20 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
1eb30 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
1eb40 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
1eb50 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
1eb60 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
1eb70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
1eb80 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1eb90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1eba0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
1ebb0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
1ebc0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
1ebd0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
1ebe0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
1ebf0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
1ec00 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
1ec10 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
1ec20 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
1ec30 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
1ec40 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
1ec50 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
1ec60 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
1ec70 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
1ec80 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
1ec90 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
1eca0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
1ecb0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
1ecc0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65  numeric identife
1ecd0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
1ece0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
1ecf0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
1ed00 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
1ed10 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
1ed20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
1ed30 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
1ed40 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1ed50 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1ed60 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
1ed70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1ed80 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1ed90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1eda0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
1edb0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
1edc0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1edd0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1ede0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
1edf0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ee00 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
1ee10 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
1ee20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1ee30 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1ee40 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1ee50 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1ee60 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
1ee70 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
1ee80 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1ee90 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
1eea0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
1eeb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
1eec0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
1eed0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
1eee0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
1eef0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
1ef00 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
1ef10 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
1ef20 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
1ef30 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
1ef40 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
1ef50 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
1ef60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
1ef70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ef80 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
1ef90 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
1efa0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
1efb0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
1efc0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
1efd0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
1efe0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
1eff0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
1f000 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1f010 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
1f020 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1f030 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
1f040 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
1f050 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
1f060 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1f070 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
1f080 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f090 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
1f0a0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
1f0b0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
1f0c0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
1f0d0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
1f0e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1f0f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
1f100 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
1f110 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
1f120 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1f130 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
1f140 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
1f150 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1f160 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
1f170 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f180 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
1f190 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
1f1a0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
1f1b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1f1c0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
1f1d0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1f1e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
1f1f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
1f200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f210 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
1f220 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
1f230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1f240 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
1f250 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
1f260 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
1f270 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
1f280 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
1f290 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1f2a0 74 2e 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  t. ^If the fifth
1f2b0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
1f2c0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
1f2d0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
1f2e0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
1f2f0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
1f300 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1f310 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
1f320 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
1f330 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1f340 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
1f350 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1f360 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
1f370 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
1f380 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
1f390 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
1f3a0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
1f3b0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
1f3c0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
1f3d0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
1f3e0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1f3f0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
1f400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
1f410 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
1f420 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
1f430 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
1f440 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
1f450 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
1f460 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1f470 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1f480 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1f490 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1f4a0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1f4b0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1f4c0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1f4d0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1f4e0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1f4f0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1f500 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1f510 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1f520 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1f530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1f540 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1f550 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1f560 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
1f570 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
1f580 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
1f590 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
1f5a0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
1f5b0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
1f5c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f5d0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
1f5e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1f5f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
1f600 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
1f610 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
1f620 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
1f630 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
1f640 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
1f650 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
1f660 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
1f670 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
1f680 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
1f690 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
1f6a0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
1f6b0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
1f6c0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
1f6d0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
1f6e0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
1f6f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1f700 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
1f710 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
1f720 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
1f730 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
1f740 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1f750 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
1f760 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
1f770 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1f780 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
1f790 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1f7a0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1f7b0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1f7c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
1f7d0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
1f7e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1f7f0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
1f800 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
1f810 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
1f820 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
1f830 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1f840 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1f850 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1f860 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1f870 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
1f880 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
1f890 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
1f8a0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
1f8b0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1f8c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1f8d0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1f8e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f8f0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
1f900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f910 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1f920 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1f930 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1f940 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1f950 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1f960 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1f970 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f980 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1f990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1f9a0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1f9b0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1f9c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f9d0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1f9e0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1f9f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1fa00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1fa10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1fa20 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1fa30 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1fa40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1fa50 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1fa60 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1fa70 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1fa80 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1fa90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1faa0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1fab0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1fac0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1fad0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1fae0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1faf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fb00 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1fb10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1fb20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1fb30 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1fb40 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1fb50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fb60 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1fb70 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
1fb80 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1fb90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
1fba0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
1fbb0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
1fbc0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
1fbd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1fbe0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
1fbf0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
1fc00 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
1fc10 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
1fc20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
1fc30 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
1fc40 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
1fc50 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
1fc60 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
1fc70 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
1fc80 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
1fc90 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
1fca0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
1fcb0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
1fcc0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1fcd0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
1fce0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
1fcf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
1fd00 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1fd10 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1fd20 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1fd30 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
1fd40 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
1fd50 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1fd60 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1fd70 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
1fd80 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
1fd90 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
1fda0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1fdb0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1fdc0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1fdd0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1fde0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1fdf0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
1fe00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1fe10 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1fe20 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1fe30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1fe40 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
1fe50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
1fe60 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
1fe70 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
1fe80 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
1fe90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1fea0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
1feb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1fec0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
1fed0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
1fee0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
1fef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ff00 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
1ff10 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1ff20 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
1ff30 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
1ff40 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
1ff50 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
1ff60 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
1ff70 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
1ff80 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
1ff90 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
1ffa0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
1ffb0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
1ffc0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
1ffd0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
1ffe0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
1fff0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
20000 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
20010 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
20020 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
20030 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
20040 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
20050 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
20060 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
20070 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
20080 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
20090 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
200a0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
200b0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
200c0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
200d0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
200e0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
200f0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
20100 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
20110 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
20120 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
20130 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
20140 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
20150 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
20160 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
20170 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
20180 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
20190 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
201a0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
201b0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
201c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
201d0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
201e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
201f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
20200 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
20210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
20220 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
20230 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
20240 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20250 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
20260 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
20270 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20280 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
20290 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
202a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
202b0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
202c0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
202d0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
202e0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
202f0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
20300 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
20310 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
20320 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
20330 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
20340 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
20350 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
20360 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
20370 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
20380 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
20390 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
203a0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
203b0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
203c0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
203d0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
203e0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
203f0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
20400 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
20410 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
20420 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
20430 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
20440 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
20450 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
20460 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20470 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
20480 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
20490 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
204a0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
204b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
204c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
204d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
204e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
204f0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
20500 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
20510 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
20520 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
20530 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
20540 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
20550 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
20560 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
20570 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
20580 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20590 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
205a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
205b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
205c0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
205d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
205e0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
205f0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
20600 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
20610 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
20620 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
20630 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
20640 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
20650 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
20660 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
20670 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
20680 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
20690 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
206a0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
206b0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
206c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
206d0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
206e0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
206f0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
20700 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
20710 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
20720 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
20730 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
20740 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20  PDATE])..*/.int 
20750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
20760 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
20770 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
20780 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
20790 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
207a0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
207b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
207c0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
207d0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
207e0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
207f0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
20800 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
20810 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
20820 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
20830 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
20840 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
20850 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
20860 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
20870 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
20880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20890 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
208a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
208b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
208c0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
208d0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
208e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
208f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20900 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
20910 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
20920 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
20930 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
20940 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
20950 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
20960 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
20970 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
20980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
20990 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
209a0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
209b0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
209c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
209d0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
209e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
209f0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
20a00 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
20a10 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
20a20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
20a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20a40 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
20a50 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
20a60 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
20a70 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
20a80 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
20a90 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
20aa0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
20ab0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
20ac0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
20ad0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
20ae0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
20af0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
20b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
20b10 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
20b20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
20b30 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
20b40 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
20b50 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
20b60 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
20b70 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
20b80 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
20b90 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
20ba0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
20bb0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
20bc0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
20bd0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
20be0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
20bf0 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
20c00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
20c10 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
20c20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
20c30 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20c40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20c50 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20c60 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
20c70 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
20c80 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
20c90 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
20ca0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
20cb0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
20cc0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
20cd0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
20ce0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
20cf0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
20d00 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
20d10 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
20d20 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
20d30 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
20d40 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
20d50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
20d60 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
20d70 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
20d80 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
20d90 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
20da0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
20db0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
20dc0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
20dd0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
20de0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
20df0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
20e00 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
20e10 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
20e20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20e30 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
20e40 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
20e50 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
20e60 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
20e70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20e80 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
20e90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20ea0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
20eb0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
20ec0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
20ed0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
20ee0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
20ef0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
20f00 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
20f10 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
20f20 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
20f30 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
20f40 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
20f50 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
20f60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
20f70 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
20f80 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
20f90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20fa0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
20fb0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
20fc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
20fd0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
20fe0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
20ff0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
21000 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
21010 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
21020 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
21030 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
21040 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
21050 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
21060 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
21070 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
21080 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
21090 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
210a0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
210b0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
210c0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
210d0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
210e0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
210f0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
21100 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
21110 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
21120 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
21130 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21140 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
21150 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
21160 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
21170 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
21180 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
21190 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
211a0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
211b0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
211c0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
211d0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
211e0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
211f0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
21200 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
21210 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
21220 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
21230 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
21240 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
21250 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
21260 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
21270 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
21280 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
21290 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
212a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
212b0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
212c0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
212d0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
212e0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
212f0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
21300 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
21310 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
21320 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
21330 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
21340 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
21350 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
21360 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
21370 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
21380 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
21390 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
213a0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
213b0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
213c0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
213d0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
213e0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
213f0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
21400 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21410 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
21420 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
21430 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
21440 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
21450 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
21460 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
21480 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
21490 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
214a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
214b0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
214c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
214d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
214e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
214f0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
21500 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21510 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
21520 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21530 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
21540 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21550 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
21560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
21570 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
21580 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21590 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
215a0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
215b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
215c0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
215d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
215e0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
215f0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
21600 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
21610 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
21620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21630 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
21640 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
21650 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
21660 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
21670 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
21680 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
21690 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
216a0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
216b0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
216c0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
216d0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
216e0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
216f0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
21700 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
21710 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
21720 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
21730 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
21740 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
21750 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
21760 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
21770 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
21780 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
21790 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
217a0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
217b0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
217c0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
217d0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
217e0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
217f0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
21800 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
21810 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
21820 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
21830 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
21840 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
21850 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
21860 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
21870 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
21880 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
21890 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
218a0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
218b0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
218c0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
218d0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
218e0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
218f0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
21900 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
21910 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
21920 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
21930 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
21940 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
21950 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
21960 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
21970 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
21980 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
21990 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
219a0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
219b0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
219c0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
219d0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
219e0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
219f0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
21a00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
21a10 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
21a20 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
21a30 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
21a40 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
21a50 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
21a60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
21a70 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
21a80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21a90 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
21aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
21ab0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
21ac0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
21ad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
21ae0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
21af0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
21b00 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
21b10 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
21b20 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
21b30 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
21b40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21b50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21b60 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
21b70 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
21b80 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
21b90 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
21ba0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
21bb0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
21bc0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
21bd0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
21be0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
21bf0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
21c00 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
21c10 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
21c20 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
21c30 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
21c40 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
21c50 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
21c60 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
21c70 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
21c80 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
21c90 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
21ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21cb0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
21cc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21cd0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
21ce0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
21cf0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
21d00 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
21d10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21d20 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
21d30 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
21d40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
21d50 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
21d60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
21d70 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
21d80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
21d90 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
21da0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
21db0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
21dc0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
21dd0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
21de0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
21df0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
21e00 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
21e10 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
21e20 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
21e30 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
21e40 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
21e50 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
21e60 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
21e70 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
21e80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
21e90 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
21ea0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
21eb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
21ec0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
21ed0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
21ee0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
21ef0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
21f00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
21f10 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
21f20 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
21f30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
21f40 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
21f50 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
21f60 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
21f70 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
21f80 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
21f90 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21fa0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
21fb0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
21fc0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
21fd0 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
21fe0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
21ff0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
22000 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
22010 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
22020 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
22030 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
22040 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
22050 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
22060 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
22070 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
22080 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
22090 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
220a0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
220b0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
220c0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
220d0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
220e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
220f0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
22100 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
22110 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
22120 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
22130 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
22140 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
22150 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
22160 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
22170 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
22180 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
22190 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
221a0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
221b0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
221c0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
221d0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
221e0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
221f0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
22200 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
22210 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
22220 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
22230 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
22240 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
22250 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
22260 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
22270 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
22280 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
22290 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
222a0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
222b0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
222c0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
222d0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
222e0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
222f0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
22300 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
22310 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
22320 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
22330 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
22340 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
22350 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
22360 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
22370 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
22380 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
22390 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
223a0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
223b0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
223c0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
223d0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
223e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
223f0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
22400 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22410 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
22420 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
22430 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
22440 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
22450 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
22460 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
22470 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
22480 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
22490 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
224a0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
224b0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
224c0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
224d0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
224e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
224f0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
22500 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
22510 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
22520 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
22530 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
22540 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
22550 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
22560 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
22570 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
22580 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
22590 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
225a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
225b0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
225c0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
225d0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
225e0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
225f0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
22600 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
22610 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
22620 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
22630 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72  6.23.1, it was r
22640 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72  equired.** after
22650 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22660 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
22670 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
22680 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a  LITE_ROW] that.*
22690 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
226a0 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ()] be called be
226b0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
226c0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
226d0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
226e0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
226f0 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
22700 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69  _reset()] in thi
22710 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72  s way would.** r
22720 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
22730 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
22740 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rn from sqlite3_
22750 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
22760 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  er.** version 3.
22770 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
22780 73 74 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c  step() began cal
22790 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
227a0 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d  set()] .** autom
227b0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
227c0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
227d0 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
227e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
227f0 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e  SE].  .**.** <b>
22800 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
22810 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
22820 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
22830 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
22840 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
22850 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
22860 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
22870 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
22880 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
22890 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
228a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
228b0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
228c0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
228d0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
228e0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
228f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22900 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
22910 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
22920 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
22930 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
22940 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
22950 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
22960 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
22970 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
22980 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
22990 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
229a0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
229b0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
229c0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
229d0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
229e0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
229f0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
22a00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22a10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22a20 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
22a30 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
22a40 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
22a50 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
22a60 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
22a70 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
22a80 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
22a90 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
22aa0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
22ab0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
22ac0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
22ad0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
22ae0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
22af0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
22b00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
22b10 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
22b20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22b30 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
22b40 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
22b50 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
22b60 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
22b70 6f 75 6e 74 28 50 29 20 74 68 65 20 6e 75 6d 62  ount(P) the numb
22b80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
22b90 20 74 68 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72   the.** of the r
22ba0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
22bb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22bc0 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] P..*/.int sqli
22bd0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
22be0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
22bf0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
22c00 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
22c10 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
22c20 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
22c30 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
22c40 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
22c50 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
22c60 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
22c70 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
22c80 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
22c90 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
22ca0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
22cb0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
22cc0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
22cd0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
22ce0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
22cf0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
22d00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
22d10 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
22d20 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
22d30 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
22d40 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
22d50 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
22d60 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
22d70 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
22d80 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
22d90 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
22da0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
22db0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
22dc0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
22dd0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22de0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
22df0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
22e00 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
22e10 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
22e20 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
22e30 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
22e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22e50 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
22e60 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
22e70 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
22e80 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
22e90 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
22ea0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
22eb0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
22ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
22ed0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
22ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
22ef0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
22f00 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
22f10 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
22f20 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
22f30 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
22f40 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
22f50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22f60 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
22f70 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
22f80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
22f90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
22fa0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
22fb0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
22fc0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
22fd0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
22fe0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
22ff0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
23000 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
23010 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
23020 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23030 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
23040 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
23050 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
23060 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
23070 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
23080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23090 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
230a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
230b0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
230c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
230d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
230e0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
230f0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
23100 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
23110 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
23120 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
23130 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
23140 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
23150 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
23160 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
23170 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
23180 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
23190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
231a0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
231b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
231c0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
231d0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
231e0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
231f0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
23200 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
23210 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
23220 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
23230 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
23240 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
23250 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
23260 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
23270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
23280 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
23290 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
232a0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
232b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
232c0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
232d0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
232e0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
232f0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
23300 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
23310 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
23320 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
23330 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
23340 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23350 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
23360 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
23370 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
23380 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
23390 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
233a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
233b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
233c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
233d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
233e0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
233f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
23400 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
23410 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
23420 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
23430 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
23440 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
23450 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
23460 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
23470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23480 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
23490 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
234a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
234b0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
234c0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
234d0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
234e0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
234f0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
23500 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
23510 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
23520 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
23530 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
23540 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
23550 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
23560 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
23570 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
23580 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
23590 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
235a0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
235b0 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
235c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
235d0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
235e0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
235f0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
23600 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
23610 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
23620 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23630 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
23640 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
23650 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23660 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
23670 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
23680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
23690 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
236a0 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
236b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
236c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
236d0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
236e0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
236f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23700 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
23710 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
23720 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
23730 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
23740 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
23750 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
23760 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
23770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23780 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
23790 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
237a0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
237b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
237c0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
237d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
237e0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
237f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
23800 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
23810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
23820 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
23830 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
23840 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
23850 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
23860 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23870 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
23880 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  ng..** ^The valu
23890 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
238a0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
238b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
238c0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
238d0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
238e0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
238f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
23900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
23910 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
23920 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
23930 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
23940 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
23950 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
23960 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23970 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
23980 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23990 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
239a0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
239b0 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
239c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
239d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
239e0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
239f0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
23a00 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
23a10 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
23a20 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
23a30 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
23a40 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
23a50 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
23a60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
23a70 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
23a80 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
23a90 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
23aa0 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
23ab0 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
23ac0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
23ad0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
23ae0 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f  -8..** ^The zero
23af0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
23b00 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
23b10 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
23b20 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
23b30 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
23b40 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
23b50 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
23b60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23b70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
23b80 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
23b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23ba0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
23bb0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
23bc0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
23bd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23be0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
23bf0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
23c00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23c10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
23c20 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
23c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
23c40 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
23c50 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
23c60 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
23c70 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
23c80 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
23c90 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
23ca0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
23cb0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
23cc0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
23cd0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
23ce0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
23cf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
23d00 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
23d10 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
23d20 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
23d30 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
23d40 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
23d50 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
23d60 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
23d70 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
23d80 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
23d90 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
23da0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
23db0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
23dc0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
23dd0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
23de0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
23df0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
23e00 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
23e10 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
23e20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
23e30 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
23e40 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
23e50 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
23e60 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
23e70 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
23e80 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
23e90 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
23ea0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
23eb0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
23ec0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
23ed0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
23ee0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
23ef0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
23f00 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
23f10 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
23f20 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23f30 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
23f40 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
23f50 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
23f60 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
23f70 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
23f80 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
23f90 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
23fa0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
23fb0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
23fc0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
23fd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
23fe0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
23ff0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
24000 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
24010 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
24020 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
24030 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
24040 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
24050 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
24060 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
24070 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
24080 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
24090 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
240a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
240b0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
240c0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
240d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
240e0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
240f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
24100 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
24110 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
24120 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
24130 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
24140 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
24150 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
24160 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
24170 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
24180 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
24190 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
241a0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
241b0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
241c0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
241d0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
241e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
241f0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
24200 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
24210 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
24220 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
24230 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
24240 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
24250 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
24260 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
24270 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
24280 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
24290 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
242a0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
242b0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
242c0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
242d0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
242e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
242f0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
24300 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
24310 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
24320 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
24330 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
24340 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
24350 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
24360 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
24370 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
24380 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
24390 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
243a0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
243b0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
243c0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
243d0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
243e0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
243f0 20 5e 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e   ^Note that when
24400 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24410 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
24420 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
24430 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
24440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24450 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
24460 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
24470 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
24480 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
24490 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
244a0 65 64 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f  ed..** ^(Type co
244b0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
244c0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
244d0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
244e0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
244f0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
24500 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
24510 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
24520 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
24530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24540 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
24550 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24560 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
24570 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
24580 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
24590 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
245a0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
245b0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
245c0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
245d0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
245e0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
245f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
24600 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
24610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24620 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
24630 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
24640 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
24650 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
24660 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
24670 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
24680 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
24690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
246a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
246b0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
246c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
246d0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
246e0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
246f0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
24700 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
24710 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   </ul>)^.**.** ^
24720 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
24730 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
24740 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
24750 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
24760 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
24770 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
24780 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
24790 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
247a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
247b0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
247c0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
247d0 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
247e0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
247f0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
24800 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
24810 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
24820 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
24830 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
24840 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
24850 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
24860 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
24870 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
24880 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
24890 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
248a0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
248b0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
248c0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
248d0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
248e0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
248f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
24900 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
24910 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
24920 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
24930 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
24940 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
24950 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
24960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24970 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
24980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24990 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
249a0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
249b0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
249c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
249d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
249e0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  li>.** </ul>)^.*
249f0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
24a00 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
24a10 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
24a20 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
24a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24a40 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
24a50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24a60 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
24a70 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
24a80 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
24a90 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
24aa0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
24ab0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
24ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24ad0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
24ae0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
24af0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
24b00 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
24b10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24b20 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
24b30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
24b40 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
24b50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24b60 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
24b70 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
24b80 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
24b90 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
24ba0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
24bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24bc0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
24bd0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
24be0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
24bf0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
24c00 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
24c10 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
24c20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
24c30 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
24c40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24c50 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
24c60 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
24c70 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
24c80 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
24c90 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
24ca0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
24cb0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
24cc0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
24cd0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
24ce0 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
24cf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24d00 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
24d10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
24d20 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
24d30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
24d40 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
24d50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
24d60 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
24d70 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
24d80 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
24d90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
24da0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
24db0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
24dc0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
24dd0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
24de0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
24df0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
24e00 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
24e10 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
24e20 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
24e30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
24e40 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
24e50 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
24e60 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
24e70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24e80 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
24e90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24ea0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
24eb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24ec0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24ed0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
24ee0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24ef0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
24f00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24f10 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
24f20 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
24f30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24f40 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24f50 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
24f60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24f70 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
24f80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
24f90 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
24fa0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24fb0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
24fc0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
24fd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
24fe0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24ff0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
25000 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25010 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
25020 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25030 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
25040 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
25050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
25060 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
25070 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
25080 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
25090 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
250a0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
250b0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
250c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
250d0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
250e0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
250f0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
25100 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
25110 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
25120 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
25130 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
25140 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
25150 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
25160 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
25170 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
25180 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
25190 2e 20 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20  . ^If execution 
251a0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
251b0 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a   failed then an.
251c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
251d0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
251e0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
251f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rned..**.** ^Thi
25200 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
25210 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
25220 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
25230 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
25240 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25250 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74  atement].  ^If t
25260 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
25270 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f  ne has not.** co
25280 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
25290 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
252a0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
252b0 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
252c0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
252d0 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  rror or an [sqli
252e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
252f0 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e  interrupt]..** ^
25300 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
25310 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
25320 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
25330 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
25340 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
25350 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
25360 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
25370 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
25380 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
25390 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a  LITE_ABORT]..*/.
253a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
253b0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
253c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
253d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
253e0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
253f0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
25400 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25410 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
25420 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
25430 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
25440 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
25450 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
25460 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
25470 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
25480 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
25490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
254a0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
254b0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
254c0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
254d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
254e0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
254f0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
25500 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
25510 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
25520 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
25530 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
25540 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
25550 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
25560 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
25570 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
25580 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25590 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
255a0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
255b0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
255c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
255d0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
255e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
255f0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
25600 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25610 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
25620 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
25630 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
25640 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
25650 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
25660 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
25670 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
25680 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
25690 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
256a0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
256b0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
256c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
256d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
256e0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
256f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25700 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
25710 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
25720 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25730 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
25740 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
25750 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
25760 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25770 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
25780 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
25790 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
257a0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
257b0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
257c0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
257d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
257e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
257f0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
25800 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
25810 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
25820 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
25830 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
25840 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
25850 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
25860 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
25870 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
25880 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25890 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
258a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
258b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
258c0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
258d0 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
258e0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
258f0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
25900 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
25910 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
25920 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
25930 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
25940 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
25950 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
25960 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
25970 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
25980 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
25990 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
259a0 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
259b0 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  * two is that th
259c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
259d0 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  er, the name of 
259e0 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
259f0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
25a00 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
25a10 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73  d in UTF-8 for s
25a20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
25a30 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
25a40 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  -16.** for sqlit
25a50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25a60 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  on16()..**.** ^T
25a70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
25a80 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
25a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25aa0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
25ab0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
25ac0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
25ad0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
25ae0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
25af0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
25b00 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
25b10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25b20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25b30 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
25b40 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
25b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
25b60 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
25b70 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
25b80 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
25b90 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
25ba0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
25bb0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
25bc0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
25bd0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
25be0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
25bf0 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
25c00 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
25c10 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
25c20 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
25c30 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
25c40 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
25c50 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41   characters.  ^A
25c60 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
25c70 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
25c80 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
25c90 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
25ca0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
25cb0 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
25cc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
25cd0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
25ce0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
25cf0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
25d00 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
25d10 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
25d20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
25d30 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
25d40 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
25d50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25d60 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
25d70 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
25d80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25d90 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
25da0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
25db0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
25dc0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
25dd0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
25de0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
25df0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
25e00 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
25e10 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
25e20 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
25e30 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
25e40 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
25e50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
25e60 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
25e70 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
25e80 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
25e90 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
25ea0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
25eb0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
25ec0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
25ed0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
25ee0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
25ef0 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
25f00 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
25f10 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
25f20 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
25f30 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
25f40 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
25f50 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
25f60 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
25f70 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
25f80 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
25f90 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
25fa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25fb0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
25fc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25fd0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
25fe0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
25ff0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
26000 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
26010 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
26020 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
26030 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
26040 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
26050 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
26060 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
26070 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
26080 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
26090 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
260a0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
260b0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
260c0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
260d0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
260e0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
260f0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
26100 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
26110 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
26120 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
26130 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
26140 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
26150 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
26160 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
26170 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
26180 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
26190 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
261a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
261b0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
261c0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
261d0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
261e0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ta()].)^.**.** T
261f0 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
26200 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
26210 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
26220 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
26230 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
26240 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
26250 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
26260 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
26270 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
26280 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
26290 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
262a0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
262b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
262c0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
262d0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
262e0 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
262f0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
26300 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
26310 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
26320 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
26330 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
26340 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
26350 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
26360 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
26370 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
26380 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
26390 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
263a0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
263b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
263c0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
263d0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
263e0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
263f0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  cks..**.** ^It i
26400 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
26410 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
26420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
26430 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
26440 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
26450 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
26460 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
26470 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
26480 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
26490 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
264a0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
264b0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
264c0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
264d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
264e0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
264f0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
26500 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
26510 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
26520 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
26530 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
26540 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
26550 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
26560 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
26570 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
26580 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
26590 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
265a0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
265b0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
265c0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
265d0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
265e0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
265f0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
26600 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
26610 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
26620 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26630 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
26640 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
26650 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
26660 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
26670 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
26680 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
26690 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
266a0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
266b0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
266c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
266d0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
266e0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
266f0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
26700 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
26710 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
26720 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
26730 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26740 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65  nctions..** ^The
26750 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69   first applicati
26760 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26770 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e  ion with a given
26780 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20   name overrides 
26790 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20  all.** built-in 
267a0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
267b0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
267c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68  connection] with
267d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
267e0 2a 2a 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61  ** ^Subsequent a
267f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26800 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20  ed functions of 
26810 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e  the same name on
26820 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20  ly override .** 
26830 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f  prior applicatio
26840 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26850 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20  ons that are an 
26860 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20  exact match for 
26870 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
26880 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
26890 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69  preferred encodi
268a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ng..**.** ^An ap
268b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
268c0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
268d0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
268e0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
268f0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
26900 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
26910 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
26920 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
26930 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
26940 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
26950 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
26960 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
26970 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
26980 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
26990 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
269a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
269b0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
269c0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
269d0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
269e0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
269f0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
26a00 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
26a10 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
26a20 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26a30 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26a40 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
26a50 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
26a60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
26a70 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
26a80 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26a90 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
26aa0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26ab0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
26ac0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
26ad0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
26ae0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
26af0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
26b00 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
26b10 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
26b20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26b30 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26b40 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
26b50 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
26b60 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26b70 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26b80 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
26b90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
26ba0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26bb0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
26bc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
26bd0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
26be0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
26bf0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
26c00 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
26c10 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
26c20 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
26c30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26c40 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
26c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26c60 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
26c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26c80 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
26c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26ca0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
26cb0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
26cc0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
26cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
26ce0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
26cf0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
26d00 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
26d10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
26d20 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
26d30 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
26d40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
26d50 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
26d60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
26d70 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
26d80 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
26d90 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
26da0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
26db0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
26dc0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
26dd0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
26de0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
26df0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
26e00 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
26e10 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
26e20 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
26e30 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
26e40 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
26e50 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
26e60 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
26e70 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
26e80 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
26e90 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
26ea0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
26eb0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
26ec0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
26ed0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
26ee0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
26ef0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
26f00 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
26f10 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
26f20 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
26f30 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
26f40 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26f50 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
26f60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
26f70 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
26f80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
26f90 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
26fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
26fb0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
26fc0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
26fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
26fe0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
26ff0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
27000 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
27010 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
27020 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
27030 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
27040 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
27050 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
27060 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
27070 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
27080 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
27090 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
270a0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
270b0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
270c0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
270d0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
270e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
270f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
27100 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
27110 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
27120 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
27130 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
27140 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
27150 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
27160 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
27170 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
27180 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
27190 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
271a0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
271b0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
271c0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
271d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
271e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
271f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27200 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
27210 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
27220 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
27230 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
27240 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
27250 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
27260 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
27270 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
27280 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
27290 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
272a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
272b0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
272c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
272d0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
272e0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
272f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27300 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
27310 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
27320 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
27330 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
27340 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
27360 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
27370 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
27380 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
27390 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
273a0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
273b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
273c0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
273d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
273e0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
273f0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
27400 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
27410 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
27420 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
27430 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
27440 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
27450 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
27460 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
27470 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
27480 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
27490 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
274a0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
274b0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
274c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
274d0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
274e0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
274f0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
27500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27510 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
27520 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
27530 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
27540 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
27550 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
27560 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
27570 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
27580 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
27590 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
275a0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
275b0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
275c0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
275d0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
275e0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
275f0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
27600 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
27610 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
27620 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
27630 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
27640 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
27650 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
27660 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
27670 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
27680 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
27690 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
276a0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
276b0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
276c0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
276d0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
276e0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
276f0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
27700 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
27710 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
27720 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
27730 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
27740 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
27750 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
27760 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
27770 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
27780 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
27790 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
277a0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
277b0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
277c0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
277d0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
277e0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
277f0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
27800 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
27810 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
27820 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
27830 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
27840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27850 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
27860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27870 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
27880 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
27890 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
278a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
278b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
278c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
278d0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
278e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
278f0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
27900 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
27910 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
27920 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
27930 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
27940 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
27950 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
27960 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
27970 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27980 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
27990 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
279a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
279b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
279c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
279d0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
279e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
279f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27a00 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
27a10 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
27a20 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
27a30 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27a40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27a50 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
27a60 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
27a70 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
27a80 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
27a90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
27aa0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
27ab0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
27ac0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
27ad0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
27ae0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
27af0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
27b00 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
27b10 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
27b20 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
27b30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
27b40 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27b50 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
27b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27b70 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27b80 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
27b90 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27ba0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
27bb0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
27bc0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
27bd0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
27be0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
27bf0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
27c00 20 49 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f   Implementions o
27c10 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
27c20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
27c30 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
27c40 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27c50 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
27c60 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
27c70 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
27c80 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
27c90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
27ca0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
27cb0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
27cc0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
27cd0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
27ce0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
27cf0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
27d00 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
27d10 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
27d20 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
27d30 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
27d40 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
27d50 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
27d60 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
27d70 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27d80 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
27d90 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
27da0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
27db0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
27dc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
27dd0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
27de0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
27df0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
27e00 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
27e10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
27e20 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
27e30 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
27e40 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
27e50 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
27e60 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
27e70 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
27e80 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
27e90 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
27ea0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
27eb0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
27ec0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
27ed0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
27ee0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
27ef0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
27f00 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
27f10 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
27f20 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
27f30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27f40 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
27f50 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
27f60 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
27f70 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
27f80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27f90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27fa0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
27fb0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
27fc0 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
27fd0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
27fe0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
27ff0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
28000 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
28010 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
28020 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
28030 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
28040 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28050 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
28060 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
28070 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
28080 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
28090 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
280a0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
280b0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
280c0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
280d0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
280e0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
280f0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
28100 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
28110 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
28120 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
28130 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
28140 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
28150 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
28160 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
28170 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
28180 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
28190 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
281a0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
281b0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
281c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
281d0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
281e0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
281f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
28200 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
28210 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
28220 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
28230 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
28240 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
28250 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
28260 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
28270 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
28280 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
28290 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
282a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
282b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
282c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
282d0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
282e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
282f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
28300 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
28310 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
28320 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
28330 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
28340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
28350 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
28360 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
28370 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
28380 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
28390 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
283a0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
283b0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
283c0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
283d0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
283e0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
283f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28400 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
28410 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28420 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
28430 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
28440 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
28450 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
28460 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
28470 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
28480 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
28490 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
284a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
284b0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
284c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
284d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
284e0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
284f0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
28500 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
28510 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
28520 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
28530 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
28540 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
28550 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
28560 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
28570 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28580 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
28590 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
285a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
285b0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
285c0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
285d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
285e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
285f0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
28600 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28610 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
28620 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
28630 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
28640 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
28650 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
28660 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
28670 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28680 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
28690 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
286a0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
286b0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
286c0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
286d0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
286e0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
286f0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
28700 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
28710 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
28720 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
28730 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
28740 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
28750 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
28760 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
28770 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
28780 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
28790 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
287a0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
287b0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
287c0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
287d0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
287e0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
287f0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
28800 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
28810 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
28820 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
28830 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
28840 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
28850 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
28860 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
28870 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
28880 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
28890 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
288a0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
288b0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
288c0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
288d0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
288e0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
288f0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
28900 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
28910 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
28920 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
28930 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
28940 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
28950 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
28960 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
28970 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
28980 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
28990 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
289a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
289b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
289c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
289d0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
289e0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
289f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
28a00 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
28a10 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
28a20 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
28a30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28a40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
28a50 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
28a60 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
28a70 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
28a80 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
28a90 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
28aa0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
28ab0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
28ac0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
28ad0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
28ae0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
28af0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
28b00 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28b10 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
28b20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
28b30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28b40 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
28b50 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
28b60 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
28b70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
28b80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
28b90 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
28ba0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
28bb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
28bc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28bd0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
28be0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
28bf0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
28c00 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
28c10 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
28c20 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
28c30 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
28c40 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
28c50 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
28c60 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
28c70 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
28c80 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
28c90 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
28ca0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
28cb0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
28cc0 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
28cd0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
28ce0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
28cf0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
28d00 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
28d10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
28d20 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
28d30 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
28d40 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
28d50 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
28d60 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
28d70 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
28d80 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
28d90 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
28da0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
28db0 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
28dc0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
28dd0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
28de0 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
28df0 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
28e00 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
28e10 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
28e20 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
28e30 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
28e40 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
28e50 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
28e60 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
28e70 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
28e80 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
28e90 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
28ea0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
28eb0 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
28ec0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
28ed0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
28ee0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
28ef0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
28f00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
28f10 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
28f20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
28f30 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
28f40 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
28f50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28f60 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
28f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
28f80 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
28f90 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
28fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28fb0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
28fc0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
28fd0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
28fe0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
28ff0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
29000 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
29010 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
29020 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
29030 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
29040 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
29050 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
29060 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
29070 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
29080 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
29090 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
290a0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
290b0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
290c0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
290d0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
290e0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
290f0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
29100 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
29110 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
29120 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
29130 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
29140 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
29150 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
29160 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
29170 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
29180 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
29190 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
291a0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
291b0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
291c0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
291d0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
291e0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
291f0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
29200 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
29210 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
29220 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
29230 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
29240 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
29250 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
29260 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
29270 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
29280 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
29290 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
292a0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
292b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
292c0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
292d0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
292e0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
292f0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
29300 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
29310 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
29320 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
29330 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
29340 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
29350 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
29360 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
29370 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29380 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
29390 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
293a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
293b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
293c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
293d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
293e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
293f0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
29400 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
29410 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
29420 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
29430 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
29440 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
29450 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29460 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
29470 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
29480 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
29490 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
294a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
294b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
294c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
294d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
294e0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
294f0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
29500 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29510 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
29520 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
29530 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
29540 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
29550 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
29560 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
29570 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
29580 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
29590 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
295a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
295b0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
295c0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
295d0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
295e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
295f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29600 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
29610 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
29620 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
29630 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
29640 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
29650 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
29660 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
29670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29680 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
29690 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
296a0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
296b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
296c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
296d0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
296e0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
296f0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
29700 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
29710 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29720 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
29730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29740 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
29750 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
29760 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
29770 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
29780 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
29790 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
297a0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
297b0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
297c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
297d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
297e0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
297f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29800 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
29810 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
29820 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
29830 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
29840 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
29850 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
29860 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29870 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
29880 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
29890 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
298a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
298b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
298c0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
298d0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
298e0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
298f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29900 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29910 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
29920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29930 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
29940 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
29950 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
29960 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
29970 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
29980 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
29990 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
299a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
299b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
299c0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
299d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
299e0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
299f0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
29a00 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
29a10 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
29a20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
29a30 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
29a40 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
29a50 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
29a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29a70 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
29a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29a90 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
29aa0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
29ab0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
29ac0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
29ad0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
29ae0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
29af0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
29b00 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
29b10 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
29b20 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
29b30 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
29b40 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
29b50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29b60 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
29b70 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
29b80 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
29b90 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
29ba0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
29bb0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
29bc0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
29bd0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
29be0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
29bf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
29c00 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
29c10 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
29c20 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
29c30 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29c40 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
29c50 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
29c60 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
29c70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
29c90 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
29ca0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
29cb0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
29cc0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
29cd0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
29ce0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
29cf0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
29d00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29d10 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
29d20 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
29d30 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
29d40 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
29d50 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
29d60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
29d70 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
29d80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29d90 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
29da0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
29db0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
29dc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29dd0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
29de0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
29df0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
29e00 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
29e10 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
29e20 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
29e30 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
29e40 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29e50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
29e60 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
29e70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29e80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
29e90 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
29ea0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
29eb0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
29ec0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
29ed0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29ee0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
29ef0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
29f00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
29f10 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
29f20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29f30 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
29f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29f50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
29f60 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
29f70 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
29f80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29f90 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
29fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29fb0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
29fc0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
29fd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
29fe0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29ff0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2a000 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2a010 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2a020 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2a030 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2a040 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2a050 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2a060 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2a070 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2a080 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2a090 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
2a0a0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
2a0b0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
2a0c0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
2a0d0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
2a0e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a0f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2a100 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
2a110 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2a120 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2a130 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2a140 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2a150 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2a160 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2a170 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2a180 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
2a190 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2a1a0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2a1b0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2a1c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2a1d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a1e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2a1f0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2a200 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2a210 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2a220 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2a230 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2a240 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2a250 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2a260 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2a270 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2a280 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2a290 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2a2a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2a2b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a2c0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2a2d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2a2e0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
2a2f0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
2a300 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
2a310 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
2a320 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
2a330 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
2a340 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
2a350 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
2a360 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2a370 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2a380 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2a390 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2a3a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2a3b0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
2a3c0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2a3d0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2a3e0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2a3f0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2a400 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
2a410 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2a420 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
2a430 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
2a440 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2a450 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
2a460 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
2a470 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
2a480 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
2a490 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
2a4a0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2a4b0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2a4c0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2a4d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2a4e0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2a4f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2a500 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2a510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2a520 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2a530 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2a540 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
2a550 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
2a560 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
2a570 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
2a580 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
2a590 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2a5a0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
2a5b0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
2a5c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a5d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2a5e0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2a5f0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2a600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a610 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a620 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2a630 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2a640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a650 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2a660 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2a670 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
2a680 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a690 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2a6a0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2a6b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2a6c0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2a6d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2a6e0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
2a6f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
2a700 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
2a710 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
2a720 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
2a730 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
2a740 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
2a750 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
2a760 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a770 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2a780 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2a790 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2a7a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a7b0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
2a7c0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
2a7d0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
2a7e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a7f0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
2a800 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
2a810 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
2a820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2a830 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
2a840 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
2a850 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
2a860 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
2a870 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
2a880 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2a890 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
2a8a0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
2a8b0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
2a8c0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
2a8d0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2a8e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2a8f0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
2a900 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a910 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2a920 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a930 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a940 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
2a950 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
2a960 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
2a970 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a980 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a990 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2a9a0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2a9b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2a9c0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2a9d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2a9e0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2a9f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2aa00 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
2aa10 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2aa20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2aa30 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
2aa40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2aa50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2aa60 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
2aa70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2aa80 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2aa90 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
2aaa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2aab0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2aac0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
2aad0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2aae0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2aaf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2ab00 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
2ab10 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2ab20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ab30 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2ab40 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2ab50 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2ab60 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2ab70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2ab80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
2ab90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2aba0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2abb0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2abc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2abd0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2abe0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2abf0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2ac00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2ac10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ac20 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2ac30 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2ac40 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2ac50 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2ac60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ac70 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
2ac80 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2ac90 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
2aca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2acb0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
2acc0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
2acd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ace0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
2acf0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
2ad00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2ad10 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
2ad20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61  to add new colla
2ad30 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74  tion sequences t
2ad40 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  o the.** [databa
2ad50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
2ad60 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
2ad70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
2ad80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2ad90 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
2ada0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2adb0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
2adc0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2add0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2ade0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
2adf0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
2ae00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2ae10 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
2ae20 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
2ae30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2ae40 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c  tion16(). ^In al
2ae50 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
2ae60 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
2ae70 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2ae80 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2ae90 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2aea0 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
2aeb0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2aec0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
2aed0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2aee0 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16LE], or [SQL
2aef0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
2af00 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
2af10 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
2af20 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
2af30 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
2af40 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
2af50 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
2af60 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
2af70 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
2af80 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  , or UTF-16 big-
2af90 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
2afa0 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68  vely. ^The.** th
2afb0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
2afc0 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
2afd0 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64  TE_UTF16] to ind
2afe0 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72  icate that the r
2aff0 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74  outine.** expect
2b000 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65  s pointers to be
2b010 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2b020 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
2b030 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65  te order, or the
2b040 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e  .** argument can
2b050 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
2b060 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68  6_ALIGNED] if th
2b070 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  e.** the routine
2b080 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
2b090 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
2b0a0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
2b0b0 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e  .** of UTF-16 in
2b0c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2b0d0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20   order..**.** A 
2b0e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
2b0f0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
2b100 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
2b110 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
2b120 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
2b130 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2b140 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
2b150 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
2b160 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2b170 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
2b180 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
2b190 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
2b1a0 2a 20 5e 45 61 63 68 20 74 69 6d 65 20 74 68 65  * ^Each time the
2b1b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
2b1c0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
2b1d0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
2b1e0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
2b1f0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2b200 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
2b210 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
2b220 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2b230 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
2b240 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b250 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
2b260 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b270 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  16()..**.** ^The
2b280 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
2b290 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c  ents to the appl
2b2a0 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
2b2b0 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
2b2c0 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
2b2d0 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
2b2e0 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61   a (length, data
2b2f0 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ) pair and encod
2b300 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
2b310 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
2b320 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
2b330 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
2b340 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
2b350 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
2b360 65 67 69 73 74 65 72 65 64 2e 20 20 54 68 65 20  egistered.  The 
2b370 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2b380 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
2b390 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
2b3a0 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
2b3b0 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
2b3c0 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
2b3d0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
2b3e0 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
2b3f0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2b400 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
2b410 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
2b420 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
2b430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b440 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b450 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2b460 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2b470 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2b480 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74  except that it t
2b490 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
2b4a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2b4b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
2b4c0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
2b4d0 6e 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  n.  ^The destruc
2b4e0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
2b4f0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2b500 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
2b510 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
2b520 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
2b530 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
2b540 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
2b550 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
2b560 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2b570 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  2()..** ^Collati
2b580 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
2b590 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
2b5a0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
2b5b0 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
2b5c0 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
2b5d0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
2b5e0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
2b5f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b600 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
2b610 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2b620 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  lose()]..**.** S
2b630 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
2b640 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b650 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
2b660 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b670 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
2b680 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2b690 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
2b6a0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2b6b0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2b6c0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2b6d0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2b6e0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2b6f0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2b700 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2b710 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2b720 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b730 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
2b740 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2b750 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2b760 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2b770 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2b780 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2b790 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2b7a0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
2b7b0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2b7c0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2b7d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b7e0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
2b7f0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
2b800 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
2b810 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2b820 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2b830 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2b840 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2b850 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2b860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b870 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
2b880 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
2b890 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
2b8a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
2b8b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b8c0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
2b8d0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
2b8e0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
2b8f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2b900 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
2b910 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
2b920 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b930 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
2b940 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
2b950 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
2b960 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2b970 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
2b980 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
2b990 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2b9a0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2b9b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b9c0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2b9d0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2b9e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2b9f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2ba00 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2ba10 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2ba20 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
2ba30 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ba40 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
2ba50 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
2ba60 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
2ba70 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
2ba80 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
2ba90 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
2baa0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
2bab0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
2bac0 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
2bad0 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
2bae0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
2baf0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
2bb00 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
2bb10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
2bb20 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
2bb30 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
2bb40 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2bb50 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2bb60 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
2bb70 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2bb80 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
2bb90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2bba0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
2bbb0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
2bbc0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2bbd0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2bbe0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2bbf0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
2bc00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2bc10 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
2bc20 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
2bc30 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
2bc40 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2bc50 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
2bc60 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
2bc70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2bc80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2bc90 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
2bca0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2bcb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
2bcc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2bcd0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
2bce0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
2bcf0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
2bd00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2bd10 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
2bd20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bd30 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
2bd40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2bd50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2bd60 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2bd70 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2bd80 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
2bd90 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
2bda0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2bdb0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2bdc0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
2bdd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2bde0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2bdf0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2be00 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
2be10 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2be20 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2be30 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
2be40 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
2be50 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
2be60 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
2be70 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
2be80 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
2be90 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
2bea0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
2beb0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
2bec0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
2bed0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2bee0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2bef0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2bf00 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2bf10 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2bf20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
2bf30 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2bf40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2bf50 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2bf60 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2bf70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2bf80 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2bf90 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
2bfa0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
2bfb0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
2bfc0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
2bfd0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
2bfe0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
2bff0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
2c000 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
2c010 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
2c020 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
2c030 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
2c040 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
2c050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2c060 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2c070 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2c080 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2c090 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2c0a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2c0b0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
2c0c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c0e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2c0f0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2c100 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2c110 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2c120 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
2c130 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
2c140 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
2c150 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
2c160 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2c170 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2c180 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
2c190 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
2c1a0 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
2c1b0 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
2c1c0 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
2c1d0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2c1e0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2c1f0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2c200 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
2c210 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
2c220 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
2c230 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2c240 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
2c250 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
2c260 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
2c270 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
2c280 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
2c290 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2c2a0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2c2b0 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
2c2c0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
2c2d0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
2c2e0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
2c2f0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2c300 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
2c310 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2c320 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
2c330 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c340 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2c350 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
2c360 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2c370 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2c380 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2c390 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2c3a0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2c3b0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2c3c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eter..**.** ^If 
2c3d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2c3e0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
2c3f0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
2c400 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
2c410 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
2c420 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
2c430 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
2c440 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
2c450 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
2c460 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72  ond. ^The number
2c470 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2c480 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
2c490 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
2c4a0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
2c4b0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
2c4c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
2c4d0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
2c4e0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
2c4f0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
2c500 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
2c510 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2c520 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
2c530 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ject..*/.int sql
2c540 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2c550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c560 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2c570 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2c580 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
2c590 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
2c5a0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2c5b0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2c5c0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2c5d0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2c5e0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
2c5f0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2c600 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2c610 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2c620 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
2c630 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
2c640 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
2c650 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
2c660 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
2c670 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
2c680 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2c690 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
2c6a0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2c6b0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
2c6c0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
2c6d0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
2c6e0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
2c6f0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
2c700 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2c710 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2c720 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
2c730 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
2c740 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
2c750 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
2c760 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
2c770 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
2c780 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
2c790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2c7a0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
2c7b0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
2c7c0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
2c7d0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
2c7e0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2c7f0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2c800 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2c810 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2c820 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2c830 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2c840 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2c850 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2c860 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
2c870 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2c880 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2c890 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
2c8a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
2c8b0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2c8c0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
2c8d0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2c8e0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
2c8f0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
2c900 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2c910 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c920 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
2c930 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
2c940 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2c950 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
2c960 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
2c970 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
2c980 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
2c990 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
2c9a0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
2c9b0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
2c9c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
2c9d0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
2c9e0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
2c9f0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
2ca00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
2ca10 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
2ca20 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
2ca30 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
2ca40 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
2ca50 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
2ca60 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
2ca70 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2ca80 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2ca90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2caa0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
2cab0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
2cac0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2cad0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
2cae0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
2caf0 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
2cb00 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
2cb10 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
2cb20 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
2cb30 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
2cb40 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
2cb50 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
2cb60 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
2cb70 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2cb80 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
2cb90 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2cba0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2cbb0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2cbc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cbd0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2cbe0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2cbf0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2cc00 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
2cc10 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
2cc20 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
2cc30 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
2cc40 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
2cc50 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
2cc60 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2cc70 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
2cc80 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
2cc90 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
2cca0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
2ccb0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
2ccc0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
2ccd0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
2cce0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
2ccf0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
2cd00 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
2cd10 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
2cd20 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
2cd30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
2cd40 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
2cd50 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
2cd60 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
2cd70 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
2cd80 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
2cd90 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
2cda0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
2cdb0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
2cdc0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
2cdd0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2cde0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
2cdf0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
2ce00 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
2ce10 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
2ce20 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
2ce30 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
2ce40 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
2ce50 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
2ce60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2ce70 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
2ce80 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
2ce90 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
2cea0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
2ceb0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
2cec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
2ced0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
2cee0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
2cef0 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
2cf00 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
2cf10 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
2cf20 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
2cf30 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
2cf40 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
2cf50 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
2cf60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cf70 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
2cf80 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
2cf90 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
2cfa0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
2cfb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2cfc0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2cfd0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2cfe0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
2cff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d000 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
2d010 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d020 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
2d030 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d040 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
2d050 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
2d060 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
2d070 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
2d080 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
2d090 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
2d0a0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
2d0b0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
2d0c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d0d0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
2d0e0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
2d0f0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
2d100 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2d110 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2d120 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
2d130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d140 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
2d150 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2d160 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2d170 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
2d180 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
2d190 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
2d1a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d1b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d1c0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
2d1d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
2d1e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2d1f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d200 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
2d210 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
2d220 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
2d230 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
2d240 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
2d250 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
2d260 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
2d270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d280 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
2d290 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2d2a0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2d2b0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
2d2c0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
2d2d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2d2e0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
2d2f0 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
2d300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2d310 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
2d320 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
2d330 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
2d340 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
2d350 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d360 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
2d370 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
2d380 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2d390 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2d3a0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2d3b0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2d3c0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2d3d0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
2d3e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2d3f0 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
2d400 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
2d410 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
2d420 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
2d430 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2d440 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2d450 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2d460 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2d470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d480 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2d490 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d4a0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2d4b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2d4c0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2d4d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2d4e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2d4f0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2d500 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
2d510 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
2d520 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2d530 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2d540 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2d550 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2d560 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2d570 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d580 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2d590 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
2d5a0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2d5b0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
2d5c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2d5d0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
2d5e0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
2d5f0 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
2d600 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
2d610 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
2d620 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2d630 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
2d640 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d650 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
2d660 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
2d670 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
2d680 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
2d690 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
2d6a0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2d6b0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2d6c0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2d6d0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
2d6e0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2d6f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
2d700 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
2d710 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
2d720 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
2d730 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  D..**.** The cal
2d740 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
2d750 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
2d760 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
2d770 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
2d780 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d790 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
2d7a0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
2d7b0 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
2d7c0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
2d7d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d7e0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
2d7f0 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
2d800 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
2d810 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
2d820 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
2d830 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
2d840 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
2d850 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
2d860 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2d870 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2d880 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d890 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2d8a0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2d8b0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2d8c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d8d0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2d8e0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2d8f0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2d900 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
2d910 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
2d920 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
2d930 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2d940 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
2d950 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
2d960 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
2d970 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
2d980 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
2d990 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
2d9a0 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
2d9b0 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
2d9c0 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
2d9d0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
2d9e0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
2d9f0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2da00 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
2da10 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2da20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
2da30 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
2da40 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
2da50 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
2da60 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
2da70 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
2da80 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
2da90 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
2daa0 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
2dab0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
2dac0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
2dad0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
2dae0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
2daf0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
2db00 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
2db10 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
2db20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
2db30 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
2db40 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
2db50 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
2db60 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
2db70 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
2db80 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2db90 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2dba0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
2dbb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2dbc0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
2dbd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2dbe0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
2dbf0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2dc00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
2dc10 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
2dc20 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
2dc30 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
2dc40 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
2dc50 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
2dc60 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
2dc70 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2dc80 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
2dc90 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
2dca0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
2dcb0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
2dcc0 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
2dcd0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2dce0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
2dcf0 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
2dd00 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2dd10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2dd20 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
2dd30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2dd40 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
2dd50 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
2dd60 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
2dd70 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2dd80 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2dd90 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2dda0 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
2ddb0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2ddc0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2ddd0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2dde0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2ddf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2de00 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2de10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2de20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2de30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2de40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
2de50 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
2de60 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2de70 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2de80 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
2de90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2dea0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
2deb0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
2dec0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2ded0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2dee0 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
2def0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
2df00 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2df10 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
2df20 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
2df30 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
2df40 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
2df50 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
2df60 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
2df70 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
2df80 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
2df90 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2dfa0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
2dfb0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
2dfc0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
2dfd0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
2dfe0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
2dff0 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
2e000 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
2e010 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
2e020 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2e030 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
2e040 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
2e050 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
2e060 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
2e070 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
2e080 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
2e090 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
2e0a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
2e0b0 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
2e0c0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
2e0d0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
2e0e0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
2e0f0 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
2e100 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
2e110 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
2e120 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
2e130 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2e140 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
2e150 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
2e160 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
2e170 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
2e180 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
2e190 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
2e1a0 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
2e1b0 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
2e1c0 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
2e1d0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
2e1e0 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
2e1f0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
2e200 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
2e210 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
2e220 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
2e230 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
2e240 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
2e250 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
2e260 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
2e270 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
2e280 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2e290 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
2e2a0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
2e2b0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
2e2c0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
2e2d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e2e0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
2e2f0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
2e300 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
2e310 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
2e320 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e330 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
2e340 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
2e350 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
2e360 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
2e370 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2e380 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
2e390 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
2e3a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
2e3b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e3c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e3d0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
2e3e0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
2e3f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e400 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
2e410 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
2e420 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
2e430 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e440 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2e450 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
2e460 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
2e470 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
2e480 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2e490 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
2e4a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e4b0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2e4c0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2e4d0 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
2e4e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
2e4f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
2e500 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71  _hook()] and [sq
2e510 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2e520 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ook()].** interf
2e530 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  aces..*/.void *s
2e540 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2e550 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
2e560 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
2e570 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
2e580 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
2e590 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
2e5a0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
2e5b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
2e5c0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
2e5d0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
2e5e0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
2e5f0 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a  shared cache}.**
2e600 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2e610 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
2e620 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
2e630 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
2e640 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
2e650 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
2e660 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
2e670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e680 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
2e690 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
2e6a0 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
2e6b0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
2e6c0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2e6d0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
2e6e0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
2e6f0 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
2e700 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20  )^.**.** ^Cache 
2e710 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
2e720 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
2e730 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
2e740 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69  ocess..** This i
2e750 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
2e760 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2e770 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
2e780 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2e790 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
2e7a0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
2e7b0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
2e7c0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
2e7d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63  y..**.** ^(The c
2e7e0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
2e7f0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
2e800 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
2e810 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
2e820 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
2e830 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2e840 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2e850 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
2e860 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
2e870 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
2e880 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
2e890 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
2e8a0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
2e8b0 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
2e8c0 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
2e8d0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a  were opened.)^.*
2e8e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2e8f0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2e900 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2e910 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2e920 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2e930 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2e940 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2e950 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2e960 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  herwise.)^.**.**
2e970 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69   ^Shared cache i
2e980 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
2e990 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
2e9a0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
2e9b0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
2e9c0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
2e9d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2e9e0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
2e9f0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
2ea00 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
2ea10 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
2ea20 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b  .** See Also:  [
2ea30 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61  SQLite Shared-Ca
2ea40 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74  che Mode].*/.int
2ea50 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
2ea60 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
2ea70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ea80 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46  EF: Attempt To F
2ea90 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
2eaa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2eab0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2eac0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
2ead0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e  tempts to free N
2eae0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61   bytes.** of hea
2eaf0 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
2eb00 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
2eb10 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ential memory al
2eb20 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c  locations.** hel
2eb30 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2eb40 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d  e library.   Mem
2eb50 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
2eb60 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
2eb70 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
2eb80 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
2eb90 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
2eba0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2ebb0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
2ebc0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
2ebd0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ebe0 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
2ebf0 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68  lly freed,.** wh
2ec00 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
2ec10 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74  e or less than t
2ec20 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
2ec30 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
2ec40 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2ec50 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2ec60 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2ec70 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2ec80 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
2ec90 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
2eca0 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
2ecb0 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73  face places a "s
2ecc0 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e  oft" limit.** on
2ecd0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
2ece0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
2ecf0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
2ed00 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
2ed10 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2ed20 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2ed30 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2ed40 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2ed50 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2ed60 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2ed70 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2ed80 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2ed90 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2eda0 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2edb0 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2edc0 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2edd0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rmed..**.** ^The
2ede0 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2edf0 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
2ee00 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2ee10 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2ee20 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2ee30 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2ee40 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2ee50 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2ee60 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2ee70 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2ee80 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2ee90 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2eea0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2eeb0 2a 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  *.** ^A negative
2eec0 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
2eed0 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
2eee0 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
2eef0 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
2ef00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
2ef10 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
2ef20 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
2ef30 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
2ef40 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
2ef50 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2ef60 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
2ef70 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
2ef80 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  o..**.** ^(SQLit
2ef90 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
2efa0 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
2efb0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2efc0 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68  it..** But if th
2efd0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2efe0 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f  t cannot be hono
2eff0 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77  red, execution w
2f000 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20  ill.** continue 
2f010 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72  without error or
2f020 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e   notification.)^
2f030 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
2f040 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61  e limit is.** ca
2f050 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
2f060 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
2f070 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
2f080 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
2f090 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2f0a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
2f0b0 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
2f0c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2f0d0 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
2f0e0 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
2f0f0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2f100 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
2f110 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
2f120 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
2f130 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2f140 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2f150 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
2f160 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
2f170 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
2f180 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
2f190 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
2f1a0 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
2f1b0 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
2f1c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2f1d0 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
2f1e0 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
2f1f0 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
2f200 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
2f210 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
2f220 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
2f230 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
2f240 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
2f250 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2f260 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
2f270 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61   CAPI3REF: Extra
2f280 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
2f290 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
2f2a0 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Table.**.** ^Thi
2f2b0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2f2c0 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74  s metadata about
2f2d0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
2f2e0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
2f2f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62  .** database tab
2f300 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
2f310 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73  ing the [databas
2f320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2f330 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61  ndle.** passed a
2f340 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
2f350 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2f360 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e  *.** ^The column
2f370 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
2f380 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
2f390 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2f3a0 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20  arameters to.** 
2f3b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
2f3c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2f3d0 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
2f3e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2f3f0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
2f400 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
2f410 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
2f420 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
2f430 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
2f440 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
2f450 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e  ULL. ^If it is N
2f460 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
2f470 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2f480 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
2f490 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
2f4a0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
2f4b0 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20  gorithm used by 
2f4c0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2f4d0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76  ine to.** resolv
2f4e0 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
2f4f0 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
2f500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2f510 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2f520 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
2f530 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
2f540 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
2f550 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
2f560 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
2f570 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
2f580 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
2f590 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79  arameters.** may
2f5a0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2f5b0 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74  ^Metadata is ret
2f5c0 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
2f5d0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
2f5e0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
2f5f0 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e  as the 5th.** an
2f600 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
2f610 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
2f620 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f  function. ^Any o
2f630 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
2f640 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
2f650 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2f660 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2f670 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
2f680 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
2f690 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b  ..**.** ^(<block
2f6a0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2f6b0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2f6c0 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
2f6d0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
2f6e0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
2f6f0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
2f700 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
2f710 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2f720 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
2f730 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
2f740 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2f750 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
2f760 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
2f770 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
2f780 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
2f790 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2f7a0 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
2f7b0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2f7c0 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
2f7d0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
2f7e0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2f7f0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
2f800 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
2f810 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
2f820 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
2f830 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2f840 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
2f850 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
2f860 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2f870 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2f880 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   ^The memory poi
2f890 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
2f8a0 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
2f8b0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
2f8c0 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
2f8d0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
2f8e0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2f8f0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
2f900 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
2f910 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
2f920 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
2f930 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
2f940 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
2f950 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
2f960 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2f970 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2f980 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2f990 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
2f9a0 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
2f9b0 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
2f9c0 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
2f9d0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
2f9e0 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
2f9f0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
2fa00 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2fa10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2fa20 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
2fa30 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2fa40 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20  ed column. ^(If 
2fa50 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
2fa60 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2fa70 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ed [INTEGER PRIM
2fa80 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c  ARY KEY] column,
2fa90 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2faa0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2fab0 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77  re set as follow
2fac0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
2fad0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
2fae0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
2faf0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
2fb00 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
2fb10 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
2fb20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
2fb30 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
2fb40 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
2fb50 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
2fb60 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
2fb70 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
2fb80 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
2fb90 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
2fba0 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
2fbb0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2fbc0 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
2fbd0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
2fbe0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
2fbf0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
2fc00 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f   found, an [erro
2fc10 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2fc20 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
2fc30 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a   message left.**
2fc40 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
2fc50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2fc60 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
2fc70 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
2fc80 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  msg()).)^.**.** 
2fc90 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c  ^This API is onl
2fca0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2fcb0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2fcc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2fcd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2fce0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2fcf0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2fd00 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
2fd10 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2fd20 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
2fd30 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
2fd40 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2fd50 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
2fd60 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
2fd70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
2fd80 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
2fd90 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
2fda0 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
2fdb0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
2fdc0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
2fdd0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
2fde0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
2fdf0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
2fe00 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
2fe10 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
2fe20 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
2fe30 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
2fe40 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
2fe50 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
2fe60 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2fe70 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
2fe80 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
2fe90 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
2fea0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2feb0 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
2fec0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
2fed0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
2fee0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
2fef0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2ff00 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2ff10 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
2ff20 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
2ff30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ff40 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2ff50 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
2ff60 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
2ff70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff80 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2ff90 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  on.**.** ^This i
2ffa0 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61  nterface loads a
2ffb0 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
2ffc0 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20  on library from 
2ffd0 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a  the named file..
2ffe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fff0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
30000 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  n() interface at
30010 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
30020 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65  n.** SQLite exte
30030 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
30040 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
30050 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a  ile zFile..**.**
30060 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e   ^The entry poin
30070 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e  t is zProc..** ^
30080 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20  zProc may be 0, 
30090 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
300a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
300b0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66  try point.** def
300c0 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
300d0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
300e0 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  "..** ^The sqlit
300f0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
30100 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  n() interface re
30110 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
30120 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
30130 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
30140 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
30150 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
30160 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
30170 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20  rs and pzErrMsg 
30180 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74  is not 0, then t
30190 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  he.** [sqlite3_l
301a0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
301b0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
301c0 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66   attempt to.** f
301d0 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69  ill *pzErrMsg wi
301e0 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  th error message
301f0 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20   text stored in 
30200 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e  memory.** obtain
30210 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
30220 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20  _malloc()]. The 
30230 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
30240 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20  .** should free 
30250 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63  this memory by c
30260 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30270 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
30280 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
30290 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
302a0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
302b0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
302c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
302d0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
302e0 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72  is API,.** other
302f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69  wise an error wi
30300 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
30310 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
30320 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
30330 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  on() SQL functio
30340 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  n]..*/.int sqlit
30350 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
30360 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
30370 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
30380 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
30390 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
303a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
303b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
303c0 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
303d0 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
303e0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
303f0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
30400 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
30410 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
30420 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
30430 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
30440 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
30450 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
30460 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
30470 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
30480 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
30490 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
304a0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
304b0 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
304c0 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70  ^So as not to op
304d0 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65  en security hole
304e0 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69  s in older appli
304f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  cations that are
30500 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74  .** unprepared t
30510 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65  o deal with exte
30520 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61  nsion loading, a
30530 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66  nd as a means of
30540 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78   disabling.** ex
30550 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
30560 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
30570 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
30580 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  L, the following
30590 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69   API.** is provi
305a0 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20  ded to turn the 
305b0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
305c0 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61  tension()] mecha
305d0 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  nism on and off.
305e0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
305f0 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66  n loading is off
30600 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65   by default. See
30610 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a   ticket #1863..*
30620 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  * ^Call the sqli
30630 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
30640 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
30650 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
30660 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74  1.** to turn ext
30670 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f  ension loading o
30680 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69  n and call it wi
30690 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74  th onoff==0 to t
306a0 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f  urn.** it back o
306b0 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74  ff again..*/.int
306c0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
306d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
306e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
306f0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
30700 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74  API3REF: Automat
30710 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
30720 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  xtensions.**.** 
30730 5e 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65  ^This API can be
30740 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67   invoked at prog
30750 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f  ram startup in o
30760 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72  rder to register
30770 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
30780 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
30790 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61  d extensions tha
307a0 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61  t will be availa
307b0 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65  ble.** to all ne
307c0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
307d0 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20  ections]..**.** 
307e0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  ^(This routine s
307f0 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
30800 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
30810 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
30820 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74  in an array that
30830 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
30840 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
30850 63 28 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f  c()].  That memo
30860 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63  ry.** is dealloc
30870 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
30880 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
30890 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  nsion()].)^.**.*
308a0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
308b0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78   registers an ex
308c0 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
308d0 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61  int that is.** a
308e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
308f0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30900 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
30910 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20  nnection].** is 
30920 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  opened using [sq
30930 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
30940 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
30950 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
30960 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
30970 20 5e 44 75 70 6c 69 63 61 74 65 20 65 78 74 65   ^Duplicate exte
30980 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63  nsions are detec
30990 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74  ted so calling t
309a0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d  his routine.** m
309b0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
309c0 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65  th the same exte
309d0 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73  nsion is harmles
309e0 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63  s..** ^Automatic
309f0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
30a00 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
30a10 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eads..*/.int sql
30a20 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
30a30 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
30a40 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
30a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30a60 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
30a70 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
30a80 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ng.**.** ^(This 
30a90 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
30aa0 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
30ab0 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
30ac0 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69  matic.** extensi
30ad0 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74  ons. It undoes t
30ae0 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
30af0 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74   prior.** [sqlit
30b00 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
30b10 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a  n()] calls.)^.**
30b20 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
30b30 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f  on disables auto
30b40 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
30b50 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
30b60 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
30b70 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
30b80 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a  nsion(void);../*
30b90 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
30ba0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
30bb0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
30bc0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
30bd0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
30be0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
30bf0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
30c00 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
30c10 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
30c20 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
30c30 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
30c40 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
30c50 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
30c60 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
30c70 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
30c80 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
30c90 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
30ca0 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
30cb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
30cc0 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
30cd0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
30ce0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
30cf0 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  mment..*/../*.**
30d00 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64   Structures used
30d10 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20   by the virtual 
30d20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a  table interface.
30d30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
30d40 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  t sqlite3_vtab s
30d50 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70  qlite3_vtab;.typ
30d60 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
30d70 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
30d80 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
30d90 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  o;.typedef struc
30da0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
30db0 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74  ursor sqlite3_vt
30dc0 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64  ab_cursor;.typed
30dd0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30de0 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33  3_module sqlite3
30df0 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20  _module;../*.** 
30e00 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
30e10 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a  l Table Object.*
30e20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
30e30 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74  te3_module {virt
30e40 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
30e50 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72  }.**.** This str
30e60 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65  ucture, sometime
30e70 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69  s called a a "vi
30e80 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30e90 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
30ea0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
30eb0 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
30ec0 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
30ed0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
30ee0 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
30ef0 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
30f00 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
30f10 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ^A virtual table
30f20 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74   module is creat
30f30 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e  ed by filling in
30f40 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a   a persistent.**
30f50 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
30f60 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  s structure and 
30f70 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65  passing a pointe
30f80 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e  r to that instan
30f90 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ce.** to [sqlite
30fa0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
30fb0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
30fc0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
30fd0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69  )]..** ^The regi
30fe0 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73  stration remains
30ff0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20   valid until it 
31000 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  is replaced by a
31010 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f   different.** mo
31020 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68  dule or until th
31030 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
31040 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20  ection] closes. 
31050 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   The content.** 
31060 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
31070 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67  e must not chang
31080 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65  e while it is re
31090 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a  gistered with.**
310a0 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
310b0 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72  nnection..*/.str
310c0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
310d0 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
310e0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
310f0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
31100 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
31110 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
31120 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
31130 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
31140 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
31150 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
31160 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
31170 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
31180 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
31190 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
311a0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
311b0 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
311c0 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
311d0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
311e0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
311f0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
31200 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
31210 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
31220 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
31230 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
31240 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
31250 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
31260 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
31270 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31280 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
31290 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
312a0 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
312b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
312c0 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
312d0 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
312e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
312f0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
31300 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
31310 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
31320 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
31330 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
31340 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
31350 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
31360 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
31370 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
31380 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
31390 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
313a0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
313b0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
313c0 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
313d0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
313e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
313f0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
31400 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
31410 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
31420 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
31430 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
31440 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
31450 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
31460 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
31470 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
31480 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
31490 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
314a0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
314b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
314c0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
314d0 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
314e0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
314f0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
31500 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31510 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
31520 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
31530 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
31540 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
31550 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
31560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31570 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
31580 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31590 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
315a0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
315b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
315c0 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
315d0 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  g);.  int (*xRen
315e0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
315f0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
31600 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a  char *zNew);.};.
31610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31620 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
31630 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74  ndexing Informat
31640 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ion.** KEYWORDS:
31650 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
31660 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nfo.**.** The sq
31670 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
31680 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
31690 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
316a0 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
316b0 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
316c0 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
316d0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
316e0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
316f0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
31700 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
31710 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
31720 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
31730 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
31740 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
31750 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
31760 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
31770 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
31780 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
31790 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
317a0 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  fields..**.** ^(
317b0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
317c0 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
317d0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
317e0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20  straints of the 
317f0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  form:.**.** <pre
31800 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c  >column OP expr<
31810 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72  /pre>.**.** wher
31820 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
31830 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
31840 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65   &gt;=.)^  ^(The
31850 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
31860 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
31870 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
31880 5b 5d 2e 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20  [].op.)^  ^(The 
31890 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
318a0 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e  umn is stored in
318b0 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  .** aConstraint[
318c0 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28  ].iColumn.)^  ^(
318d0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
318e0 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
318f0 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
31900 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
31910 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
31920 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
31930 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
31940 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
31950 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
31960 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  t.)^.**.** ^The 
31970 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
31980 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
31990 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
319a0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
319b0 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
319c0 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
319d0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45  tions to the WHE
319e0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
319f0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
31a00 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
31a10 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
31a20 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
31a30 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
31a40 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e  le..** ^The aCon
31a50 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
31a60 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45  only reports WHE
31a70 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
31a80 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65  that are.** rele
31a90 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74  vant to the part
31aa0 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74  icular virtual t
31ab0 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69  able being queri
31ac0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72  ed..**.** ^Infor
31ad0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
31ae0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
31af0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
31b00 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61  rderBy[]..** ^Ea
31b10 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
31b20 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
31b30 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
31b40 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
31b50 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
31b60 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
31b70 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
31b80 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
31b90 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
31ba0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
31bb0 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
31bc0 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49  lter.  ^If argvI
31bd0 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
31be0 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
31bf0 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
31c00 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
31c10 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
31c20 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
31c30 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
31c40 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
31c50 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61  .  ^(If aConstra
31c60 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
31c70 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
31c80 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
31c90 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
31ca0 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
31cb0 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
31cc0 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
31cd0 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
31ce0 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a  by SQLite.)^.**.
31cf0 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61  ** ^The idxNum a
31d00 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
31d10 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
31d20 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  d passed into th
31d30 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d  e.** [xFilter] m
31d40 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69  ethod..** ^[sqli
31d50 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75  te3_free()] is u
31d60 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50  sed to free idxP
31d70 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  tr if and only i
31d80 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49  f.** needToFreeI
31d90 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
31da0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42  *.** ^The orderB
31db0 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20  yConsumed means 
31dc0 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d  that output from
31dd0 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78   [xFilter]/[xNex
31de0 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  t] will occur in
31df0 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
31e00 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
31e10 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
31e20 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
31e30 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
31e40 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
31e50 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
31e60 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
31e70 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
31e80 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
31e90 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
31ea0 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
31eb0 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
31ec0 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
31ed0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
31ee0 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
31ef0 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
31f00 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
31f10 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
31f20 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
31f30 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
31f40 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f  ately log(N)..*/
31f50 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
31f60 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f  index_info {.  /
31f70 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e  * Inputs */.  in
31f80 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
31f90 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
31fa0 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
31fb0 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a   aConstraint */.
31fc0 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
31fd0 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
31fe0 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  t {.     int iCo
31ff0 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
32000 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
32010 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
32020 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  f constraint */.
32030 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
32040 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
32050 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
32060 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e  rator */.     un
32070 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62  signed char usab
32080 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20  le;     /* True 
32090 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
320a0 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a  nt is usable */.
320b0 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66       int iTermOf
320c0 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f  fset;          /
320d0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
320e0 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73  y - xBestIndex s
320f0 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a  hould ignore */.
32100 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
32110 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
32120 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63  Table of WHERE c
32130 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
32140 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65  s */.  int nOrde
32150 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
32160 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74    /* Number of t
32170 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
32180 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
32190 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
321a0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
321b0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
321c0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
321d0 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
321e0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
321f0 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
32200 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
32210 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
32220 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64  SC. */.  } *aOrd
32230 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
32240 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
32250 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
32260 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
32270 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
32280 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
32290 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
322a0 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
322b0 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
322c0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
322d0 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
322e0 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
322f0 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
32300 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
32310 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
32320 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
32330 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
32340 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69  ntUsage;.  int i
32350 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20  dxNum;          
32360 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
32370 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79  used to identify
32380 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20   the index */.  
32390 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20  char *idxStr;   
323a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
323b0 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f  ring, possibly o
323c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
323d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20  ite3_malloc */. 
323e0 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49   int needToFreeI
323f0 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46  dxStr;      /* F
32400 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67  ree idxStr using
32410 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
32420 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74  if true */.  int
32430 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
32440 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
32450 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72  if output is alr
32460 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a  eady ordered */.
32470 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74    double estimat
32480 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20  edCost;      /* 
32490 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f  Estimated cost o
324a0 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64  f using this ind
324b0 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65  ex */.};.#define
324c0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
324d0 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32  NSTRAINT_EQ    2
324e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
324f0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
32500 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65  _GT    4.#define
32510 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
32520 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38  NSTRAINT_LE    8
32530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32540 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
32550 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e  _LT    16.#defin
32560 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
32570 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20  ONSTRAINT_GE    
32580 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
32590 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
325a0 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a  NT_MATCH 64../*.
325b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
325c0 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
325d0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
325e0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
325f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
32600 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
32610 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
32620 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d  able module] nam
32630 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61  e..** ^Module na
32640 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69  mes must be regi
32650 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a  stered before.**
32660 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20   creating a new 
32670 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
32680 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65  using the module
32690 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e   and before usin
326a0 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69  g a.** preexisti
326b0 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ng [virtual tabl
326c0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  e] for the modul
326d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f  e..**.** ^The mo
326e0 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67  dule name is reg
326f0 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b  istered on the [
32700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32710 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a  ion] specified.*
32720 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  * by the first p
32730 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20  arameter.  ^The 
32740 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  name of the modu
32750 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  le is given by t
32760 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  he .** second pa
32770 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74  rameter.  ^The t
32780 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
32790 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
327a0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
327b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72  tion of the [vir
327c0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
327d0 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74  e].   ^The fourt
327e0 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  h.** parameter i
327f0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63  s an arbitrary c
32800 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74  lient data point
32810 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
32820 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74  d through.** int
32830 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20  o the [xCreate] 
32840 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
32850 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69  ethods of the vi
32860 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
32870 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77  le.** when a new
32880 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
32890 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74  s be being creat
328a0 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69  ed or reinitiali
328b0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  zed..**.** ^The 
328c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
328d0 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72  odule_v2() inter
328e0 66 61 63 65 20 68 61 73 20 61 20 66 69 66 74 68  face has a fifth
328f0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
32900 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
32910 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72   to a destructor
32920 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74   for the pClient
32930 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77  Data.  ^SQLite w
32940 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ill.** invoke th
32950 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
32960 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20  ction (if it is 
32970 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53  not NULL) when S
32980 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67  QLite.** no long
32990 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c  er needs the pCl
329a0 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72  ientData pointer
329b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
329c0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a  create_module().
329d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
329e0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71  equivalent to sq
329f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
32a00 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ule_v2() with a 
32a10 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74  NULL.** destruct
32a20 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
32a30 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32a40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32a60 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
32a70 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
32a80 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
32a90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
32aa0 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
32ab0 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
32ac0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
32ad0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
32ae0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
32af0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
32b00 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
32b10 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta          /* C
32b20 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
32b30 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
32b40 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
32b50 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
32b60 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
32b70 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
32b80 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
32b90 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
32ba0 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
32bb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32bc0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
32bd0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
32be0 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
32bf0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
32c00 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
32c10 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
32c20 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
32c30 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a  Data,         /*
32c40 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
32c50 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
32c60 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
32c70 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
32c80 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
32c90 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
32ca0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
32cb0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
32cc0 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62  able Instance Ob
32cd0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
32ce0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
32cf0 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
32d00 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
32d10 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
32d20 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
32d30 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  .** of this obje
32d40 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  ct to describe a
32d50 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
32d60 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ance.** of the [
32d70 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20  virtual table]. 
32d80 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
32d90 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
32da0 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
32db0 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
32dc0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
32dd0 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75  ation..** The pu
32de0 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75  rpose of this su
32df0 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64  perclass is to d
32e00 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69  efine certain fi
32e10 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  elds that are.**
32e20 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d   common to all m
32e30 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
32e40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69  tions..**.** ^Vi
32e50 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
32e60 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
32e70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
32e80 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
32e90 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
32ea0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
32eb0 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72  rintf()] to zErr
32ec0 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
32ed0 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
32ee0 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
32ef0 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
32f00 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
32f10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
32f20 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ].** prior to as
32f30 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
32f40 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
32f50 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72    ^After the err
32f60 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73  or message.** is
32f70 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f   delivered up to
32f80 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c   the client appl
32f90 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72  ication, the str
32fa0 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ing will be auto
32fb0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65  matically.** fre
32fc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72  ed by sqlite3_fr
32fd0 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72  ee() and the zEr
32fe0 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20  rMsg field will 
32ff0 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74  be zeroed..*/.st
33000 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
33010 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69  b {.  const sqli
33020 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64  te3_module *pMod
33030 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64  ule;  /* The mod
33040 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72  ule for this vir
33050 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20  tual table */.  
33060 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20  int nRef;       
33070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33080 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45  /* NO LONGER USE
33090 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  D */.  char *zEr
330a0 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
330b0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
330c0 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
330d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
330e0 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
330f0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
33100 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
33110 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
33120 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
33130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33140 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43   Virtual Table C
33150 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20  ursor Object.** 
33160 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
33170 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76  3_vtab_cursor {v
33180 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72  irtual table cur
33190 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  sor}.**.** Every
331a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
331b0 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
331c0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
331d0 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
331e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
331f0 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65  ture to describe
33200 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
33210 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  int into the.** 
33220 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
33230 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
33240 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
33250 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
33260 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
33270 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
33280 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f  e.** [sqlite3_mo
33290 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70  dule.xOpen | xOp
332a0 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  en] method of th
332b0 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65  e module and are
332c0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79   destroyed.** by
332d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f   the [sqlite3_mo
332e0 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43  dule.xClose | xC
332f0 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43  lose] method.  C
33300 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a  ursors are used.
33310 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74  ** by the [xFilt
33320 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78  er], [xNext], [x
33330 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c  Eof], [xColumn],
33340 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65   and [xRowid] me
33350 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20  thods.** of the 
33360 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
33370 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
33380 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
33390 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
333a0 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
333b0 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
333c0 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
333d0 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
333e0 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
333f0 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
33400 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
33410 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
33420 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
33430 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
33440 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
33450 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
33460 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
33470 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
33480 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
33490 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
334a0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
334b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
334c0 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
334d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
334e0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
334f0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
33500 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20  e The Schema Of 
33510 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a  A Virtual Table.
33520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65  **.** ^The [xCre
33530 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
33540 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ct] methods of a
33550 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
33560 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20  le module] call 
33570 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a  this interface.*
33580 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
33590 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
335a0 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
335b0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
335c0 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
335d0 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
335e0 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  mplement..*/.int
335f0 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
33600 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
33610 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
33620 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33630 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
33640 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
33650 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a  rtual Table.**.*
33660 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c  * ^(Virtual tabl
33670 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
33680 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
33690 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
336a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
336b0 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
336c0 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
336d0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
336e0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
336f0 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
33700 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
33710 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
33720 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
33730 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29   be overloaded.)
33740 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41  ^.**.** ^(This A
33750 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
33760 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
33770 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
33780 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
33790 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
337a0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
337b0 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
337c0 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
337d0 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
337e0 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
337f0 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
33800 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20   is created.)^  
33810 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
33820 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
33830 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
33840 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
33850 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
33860 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
33870 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
33880 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
33890 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
338a0 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
338b0 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
338c0 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63  placeholder func
338d0 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
338e0 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
338f0 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  y a [virtual tab
33900 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  le]..*/.int sqli
33910 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e  te3_overload_fun
33920 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ction(sqlite3*, 
33930 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
33940 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29  cName, int nArg)
33950 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
33960 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
33970 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
33980 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62  anism defined ab
33990 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20  ove (back up.** 
339a0 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d  to a comment rem
339b0 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20  arkably similar 
339c0 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20  to this one) is 
339d0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
339e0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
339f0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
33a00 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
33a10 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
33a20 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
33a30 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
33a40 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
33a50 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
33a60 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
33a70 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
33a80 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
33a90 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
33aa0 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
33ab0 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
33ac0 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
33ad0 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
33ae0 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
33af0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
33b00 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t..*/../*.** CAP
33b10 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
33b20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  To An Open BLOB.
33b30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c  ** KEYWORDS: {BL
33b40 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42  OB handle} {BLOB
33b50 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20   handles}.**.** 
33b60 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
33b70 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
33b80 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
33b90 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b  OB on which.** [
33ba0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33bb0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
33bc0 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65  BLOB I/O] can be
33bd0 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e   performed..** ^
33be0 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20  Objects of this 
33bf0 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64  type are created
33c00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33c10 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64  b_open()].** and
33c20 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
33c30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
33c40 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  e()]..** ^The [s
33c50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
33c60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33c70 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69  _blob_write()] i
33c80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e  nterfaces.** can
33c90 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64   be used to read
33ca0 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20   or write small 
33cb0 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74  subsections of t
33cc0 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65  he BLOB..** ^The
33cd0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
33ce0 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
33cf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
33d00 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69  ze of the BLOB i
33d10 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65  n bytes..*/.type
33d20 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
33d30 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f  e3_blob sqlite3_
33d40 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  blob;../*.** CAP
33d50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c  I3REF: Open A BL
33d60 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74  OB For Increment
33d70 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54  al I/O.**.** ^(T
33d80 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f  his interfaces o
33d90 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e  pens a [BLOB han
33da0 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f  dle | handle] to
33db0 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65   the BLOB locate
33dc0 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77  d.** in row iRow
33dd0 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
33de0 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69  , table zTable i
33df0 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a  n database zDb;.
33e00 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** in other word
33e10 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42  s, the same BLOB
33e20 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73   that would be s
33e30 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  elected by:.**.*
33e40 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53  * <pre>.**     S
33e50 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52  ELECT zColumn FR
33e60 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48  OM zDb.zTable WH
33e70 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52  ERE [rowid] = iR
33e80 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  ow;.** </pre>)^.
33e90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c  **.** ^If the fl
33ea0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
33eb0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
33ec0 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e  the BLOB is open
33ed0 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61  ed for read.** a
33ee0 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
33ef0 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c   ^If it is zero,
33f00 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
33f10 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63  ned for read acc
33f20 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e  ess..** ^It is n
33f30 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
33f40 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
33f50 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20  t is part of an 
33f60 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79  index or primary
33f70 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69   .** key for wri
33f80 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69  ting. ^If [forei
33f90 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
33fa0 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c  ts] are enabled,
33fb0 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70   it is .** not p
33fc0 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
33fd0 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
33fe0 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c   part of a [chil
33ff0 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69  d key] for writi
34000 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  ng..**.** ^Note 
34010 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
34020 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68  e name is not th
34030 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20  e filename that 
34040 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
34050 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74  database but rat
34060 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63  her the symbolic
34070 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
34080 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70  abase that.** ap
34090 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20  pears after the 
340a0 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20  AS keyword when 
340b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
340c0 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20  connected using 
340d0 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f  [ATTACH]..** ^Fo
340e0 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
340f0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61  ase file, the da
34100 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
34110 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54  main"..** ^For T
34120 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20  EMP tables, the 
34130 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
34140 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e   "temp"..**.** ^
34150 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51  (On success, [SQ
34160 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
34170 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
34180 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
34190 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
341a0 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
341b0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
341c0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
341d0 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65  nd *ppBlob is se
341e0 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c  t.** to be a nul
341f0 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20  l pointer.)^.** 
34200 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73  ^This function s
34210 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  ets the [databas
34220 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72  e connection] er
34230 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
34240 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
34250 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
34260 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
34270 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
34280 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a  ] and related.**
34290 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74   functions. ^Not
342a0 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c  e that the *ppBl
342b0 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  ob variable is a
342c0 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65  lways initialize
342d0 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68  d in a.** way th
342e0 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65  at makes it safe
342f0 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
34300 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
34310 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20  ] on *ppBlob.** 
34320 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
34330 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
34340 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75  lure of this rou
34350 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  tine..**.** ^(If
34360 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20   the row that a 
34370 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e  BLOB handle poin
34380 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65  ts to is modifie
34390 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41  d by an.** [UPDA
343a0 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f  TE], [DELETE], o
343b0 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  r by [ON CONFLIC
343c0 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a  T] side-effects.
343d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  ** then the BLOB
343e0 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65   handle is marke
343f0 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a  d as "expired"..
34400 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20  ** This is true 
34410 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66  if any column of
34420 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e   the row is chan
34430 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75  ged, even a colu
34440 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  mn.** other than
34450 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f   the one the BLO
34460 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e  B handle is open
34470 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73   on.)^.** ^Calls
34480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
34490 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
344a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
344b0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78  e()] for.** a ex
344c0 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c  pired BLOB handl
344d0 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72  e fail with an r
344e0 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
344f0 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
34500 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74   ^(Changes writt
34510 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70  en into a BLOB p
34520 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42  rior to the BLOB
34530 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f   expiring are no
34540 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t.** rolled back
34550 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69   by the expirati
34560 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20  on of the BLOB. 
34570 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69   Such changes wi
34580 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ll eventually.**
34590 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74   commit if the t
345a0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69  ransaction conti
345b0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
345c0 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65  on.)^.**.** ^Use
345d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
345e0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
345f0 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69  rface to determi
34600 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ne the size of.*
34610 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f  * the opened blo
34620 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66  b.  ^The size of
34630 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20   a blob may not 
34640 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68  be changed by th
34650 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  is.** interface.
34660 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54    Use the [UPDAT
34670 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  E] SQL command t
34680 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  o change the siz
34690 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a  e of a.** blob..
346a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
346b0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
346c0 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  b()] and [sqlite
346d0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
346e0 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  b()] interfaces.
346f0 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74  ** and the built
34700 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53  -in [zeroblob] S
34710 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  QL function can 
34720 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69  be used, if desi
34730 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74  red,.** to creat
34740 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f  e an empty, zero
34750 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20  -filled blob in 
34760 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72  which to read or
34770 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20   write using.** 
34780 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
34790 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61  **.** To avoid a
347a0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20   resource leak, 
347b0 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42  every open [BLOB
347c0 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20   handle] should 
347d0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65  eventually.** be
347e0 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63   released by a c
347f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34800 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
34810 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
34820 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
34830 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
34840 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
34850 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
34860 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
34870 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
34880 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
34890 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
348a0 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
348b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
348c0 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42  EF: Close A BLOB
348d0 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43   Handle.**.** ^C
348e0 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42  loses an open [B
348f0 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  LOB handle]..**.
34900 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c  ** ^Closing a BL
34910 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74  OB shall cause t
34920 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  he current trans
34930 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74  action to commit
34940 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65  .** if there are
34950 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c   no other BLOBs,
34960 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70   no pending prep
34970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c  ared statements,
34980 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61   and the.** data
34990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
349a0 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69  is in [autocommi
349b0 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20  t mode]..** ^If 
349c0 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20  any writes were 
349d0 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42  made to the BLOB
349e0 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20  , they might be 
349f0 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a  held in cache.**
34a00 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65   until the close
34a10 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68   operation if th
34a20 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a  ey will fit..**.
34a30 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65  ** ^(Closing the
34a40 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63   BLOB often forc
34a50 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a  es the changes.*
34a60 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e  * out to disk an
34a70 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20  d so if any I/O 
34a80 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68  errors occur, th
34a90 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f  ey will likely o
34aa0 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74  ccur.** at the t
34ab0 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f  ime when the BLO
34ac0 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e  B is closed.  An
34ad0 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  y errors that oc
34ae0 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c  cur during.** cl
34af0 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74  osing are report
34b00 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  ed as a non-zero
34b10 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e   return value.)^
34b20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f  .**.** ^(The BLO
34b30 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f  B is closed unco
34b40 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76  nditionally.  Ev
34b50 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69  en if this routi
34b60 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ne returns.** an
34b70 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65   error code, the
34b80 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63   BLOB is still c
34b90 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  losed.)^.**.** ^
34ba0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
34bb0 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c  tine with a null
34bc0 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61   pointer (such a
34bd0 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72  s would be retur
34be0 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c  ned.** by a fail
34bf0 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ed call to [sqli
34c00 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34c10 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
34c20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71  no-op..*/.int sq
34c30 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
34c40 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
34c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34c60 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69  F: Return The Si
34c70 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c  ze Of An Open BL
34c80 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  OB.**.** ^Return
34c90 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79  s the size in by
34ca0 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  tes of the BLOB 
34cb0 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74  accessible via t
34cc0 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  he .** successfu
34cd0 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42  lly opened [BLOB
34ce0 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20   handle] in its 
34cf0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20  only argument.  
34d00 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e  ^The.** incremen
34d10 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75  tal blob I/O rou
34d20 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72  tines can only r
34d30 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69  ead or overwriti
34d40 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62  ng existing.** b
34d50 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65  lob content; the
34d60 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  y cannot change 
34d70 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
34d80 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ob..**.** This r
34d90 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
34da0 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
34db0 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
34dc0 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
34dd0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
34de0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
34df0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
34e00 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
34e10 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
34e20 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
34e30 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
34e40 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
34e50 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
34e60 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
34e70 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
34e80 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
34e90 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
34ea0 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73  havior..*/.int s
34eb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
34ec0 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
34ed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34ee0 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72  EF: Read Data Fr
34ef0 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
34f00 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28  entally.**.** ^(
34f10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
34f20 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61   used to read da
34f30 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20  ta from an open 
34f40 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
34f50 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  to a.** caller-s
34f60 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
34f70 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
34f80 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
34f90 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d  buffer Z.** from
34fa0 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
34fb0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
34fc0 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a  et iOffset.)^.**
34fd0 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
34fe0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
34ff0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
35000 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
35010 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
35020 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
35030 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
35040 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20  is read.  ^If N 
35050 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a  or iOffset is.**
35060 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
35070 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
35080 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
35090 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
350a0 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66  .** ^The size of
350b0 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68   the blob (and h
350c0 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
350d0 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
350e0 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
350f0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
35100 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
35110 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
35120 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  face..**.** ^An 
35130 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
35140 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20  from an expired 
35150 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61  [BLOB handle] fa
35160 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65  ils with an.** e
35170 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
35180 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
35190 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
351a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
351b0 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
351c0 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
351d0 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20  wise, an [error 
351e0 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74  code] or an [ext
351f0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
35200 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
35210 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
35220 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
35230 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
35240 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
35250 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
35260 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
35270 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
35280 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
35290 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
352a0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
352b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
352c0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
352d0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
352e0 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
352f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
35300 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
35310 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
35320 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
35330 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
35340 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
35350 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a  ob_write()]..*/.
35360 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
35370 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c  _read(sqlite3_bl
35380 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69  ob *, void *Z, i
35390 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt N, int iOffse
353a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
353b0 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20  REF: Write Data 
353c0 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72  Into A BLOB Incr
353d0 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20  ementally.**.** 
353e0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  ^This function i
353f0 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20  s used to write 
35400 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65  data into an ope
35410 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
35420 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  from a.** caller
35430 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
35440 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61  . ^N bytes of da
35450 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72  ta are copied fr
35460 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a  om the buffer Z.
35470 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e  ** into the open
35480 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20   BLOB, starting 
35490 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  at offset iOffse
354a0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
354b0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
354c0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
354d0 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
354e0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
354f0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
35500 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
35510 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
35520 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
35530 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
35540 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
35550 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
35560 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
35570 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
35580 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
35590 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74   of the BLOB; it
355a0 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
355b0 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
355c0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c  the size of a BL
355d0 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  OB using this AP
355e0 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74  I..** ^If offset
355f0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
35600 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
35610 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
35620 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
35630 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
35640 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
35650 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e  a is written.  ^
35660 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  If N is.** less 
35670 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54  than zero [SQLIT
35680 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
35690 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
356a0 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20   is written..** 
356b0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
356c0 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20  BLOB (and hence 
356d0 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
356e0 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
356f0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
35700 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
35710 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
35720 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
35730 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
35740 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61  pt to write to a
35750 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
35760 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
35770 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
35780 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
35790 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20  BORT].  ^Writes 
357a0 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74  to the BLOB that
357b0 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66   occurred.** bef
357c0 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61  ore the [BLOB ha
357d0 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72  ndle] expired ar
357e0 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63  e not rolled bac
357f0 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69  k by the.** expi
35800 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61  ration of the ha
35810 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20  ndle, though of 
35820 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61  course those cha
35830 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61  nges might.** ha
35840 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74  ve been overwrit
35850 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65  ten by the state
35860 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65  ment that expire
35870 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  d the BLOB handl
35880 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72  e.** or by other
35890 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61   independent sta
358a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
358b0 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c  (On success, sql
358c0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
358d0 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
358e0 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
358f0 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f  e, an  [error co
35900 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
35910 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
35920 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
35930 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35940 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
35950 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
35960 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
35970 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
35980 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
35990 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
359a0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
359b0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
359c0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
359d0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
359e0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
359f0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
35a00 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
35a10 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
35a20 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
35a30 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
35a40 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
35a50 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
35a60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
35a70 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _read()]..*/.int
35a80 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
35a90 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ite(sqlite3_blob
35aa0 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   *, const void *
35ab0 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f  z, int n, int iO
35ac0 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
35ad0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
35ae0 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a   File System Obj
35af0 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  ects.**.** A vir
35b00 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
35b10 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
35b20 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
35b30 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
35b40 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
35b50 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
35b60 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
35b70 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
35b80 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f  SQLite builds co
35b90 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
35ba0 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
35bb0 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
35bc0 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
35bd0 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
35be0 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
35bf0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
35c00 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
35c10 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
35c20 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
35c30 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
35c40 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
35c50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
35c60 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66  fs_find() interf
35c70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35c80 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67  inter to a VFS g
35c90 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a  iven its name..*
35ca0 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73  * ^Names are cas
35cb0 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20  e sensitive..** 
35cc0 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d  ^Names are zero-
35cd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
35ce0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66   strings..** ^If
35cf0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
35d00 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ch, a NULL point
35d10 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
35d20 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20  ** ^If zVfsName 
35d30 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
35d40 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
35d50 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
35d60 5e 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72  ^New VFSes are r
35d70 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
35d80 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
35d90 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20  ter()..** ^Each 
35da0 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20  new VFS becomes 
35db0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
35dc0 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  if the makeDflt 
35dd0 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20  flag is set..** 
35de0 5e 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61  ^The same VFS ca
35df0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
35e00 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
35e10 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a  ithout injury..*
35e20 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78  * ^To make an ex
35e30 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20  isting VFS into 
35e40 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c  the default VFS,
35e50 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61   register it aga
35e60 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d  in.** with the m
35e70 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74  akeDflt flag set
35e80 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72  .  If two differ
35e90 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74  ent VFSes with t
35ea0 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20  he.** same name 
35eb0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20  are registered, 
35ec0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
35ed0 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61  undefined.  If a
35ee0 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73  .** VFS is regis
35ef0 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d  tered with a nam
35f00 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f  e that is NULL o
35f10 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
35f20 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  g,.** then the b
35f30 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
35f40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72  ined..**.** ^Unr
35f50 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69  egister a VFS wi
35f60 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  th the sqlite3_v
35f70 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20  fs_unregister() 
35f80 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28  interface..** ^(
35f90 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  If the default V
35fa0 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72  FS is unregister
35fb0 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20  ed, another VFS 
35fc0 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20  is chosen as.** 
35fd0 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68  the default.  Th
35fe0 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65  e choice for the
35ff0 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69   new VFS is arbi
36000 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69  trary.)^.*/.sqli
36010 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
36020 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
36030 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
36040 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
36050 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
36060 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
36070 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
36080 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
36090 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
360a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
360b0 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20  : Mutexes.**.** 
360c0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
360d0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
360e0 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
360f0 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
36100 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  n. Though they a
36110 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
36120 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
36130 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
36140 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
36150 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
36160 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
36170 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
36180 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
36190 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
361a0 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
361b0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
361c0 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65  ations.** of the
361d0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
361e0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
361f0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
36200 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
36210 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
36220 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
36230 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
36240 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
36250 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
36260 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
36270 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  core:.**.** <ul>
36280 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
36290 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c  E_MUTEX_OS2.** <
362a0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
362b0 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c  EX_PTHREAD.** <l
362c0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
362d0 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_W32.** <li>   
362e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
362f0 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  P.** </ul>)^.**.
36300 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d  ** ^The SQLITE_M
36310 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
36320 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
36330 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  t of routines.**
36340 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
36350 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
36360 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
36370 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69  r use in.** a si
36380 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
36390 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65  plication.  ^The
363a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
363b0 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
363c0 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
363d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
363e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
363f0 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
36400 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f  ate for use on O
36410 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57  S/2, Unix, and W
36420 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  indows..**.** ^(
36430 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
36440 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  piled with the S
36450 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44  QLITE_MUTEX_APPD
36460 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a  EF preprocessor.
36470 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  ** macro defined
36480 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45   (with "-DSQLITE
36490 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22  _MUTEX_APPDEF=1"
364a0 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78  ), then no mutex
364b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
364c0 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77  on is included w
364d0 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e  ith the library.
364e0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68   In this case th
364f0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
36500 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63   must supply a c
36510 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c  ustom mutex impl
36520 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67  ementation using
36530 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
36540 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
36550 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69  tion of the sqli
36560 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e  te3_config() fun
36570 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20  ction.** before 
36580 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
36590 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20  initialize() or 
365a0 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63  any other public
365b0 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e   sqlite3_.** fun
365c0 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73  ction that calls
365d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
365e0 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ize().)^.**.** ^
365f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
36600 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  x_alloc() routin
36610 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65  e allocates a ne
36620 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72  w.** mutex and r
36630 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
36640 20 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72   to it. ^If it r
36650 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74  eturns NULL.** t
36660 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61  hat means that a
36670 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74   mutex could not
36680 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20   be allocated.  
36690 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20  ^SQLite.** will 
366a0 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
366b0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
366c0 72 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67  rror.  ^(The arg
366d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
366e0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
366f0 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  ) is one of thes
36700 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
36710 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  nts:.**.** <ul>.
36720 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
36730 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c  MUTEX_FAST.** <l
36740 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36750 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c  _RECURSIVE.** <l
36760 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36770 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a  _STATIC_MASTER.*
36780 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
36790 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a  UTEX_STATIC_MEM.
367a0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
367b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
367c0 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  2.** <li>  SQLIT
367d0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50  E_MUTEX_STATIC_P
367e0 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RNG.** <li>  SQL
367f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
36800 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  _LRU.** <li>  SQ
36810 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
36820 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29  C_LRU2.** </ul>)
36830 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ^.**.** ^The fir
36840 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  st two constants
36850 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46   (SQLITE_MUTEX_F
36860 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AST and SQLITE_M
36870 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a  UTEX_RECURSIVE).
36880 2a 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  ** cause sqlite3
36890 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74  _mutex_alloc() t
368a0 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65  o create.** a ne
368b0 77 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e  w mutex.  ^The n
368c0 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75  ew mutex is recu
368d0 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54  rsive when SQLIT
368e0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
368f0 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74  E.** is used but
36900 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79   not necessarily
36910 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f   so when SQLITE_
36920 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73  MUTEX_FAST is us
36930 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  ed..** The mutex
36940 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36950 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
36960 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74   make a distinct
36970 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
36980 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36990 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45  RSIVE and SQLITE
369a0 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69  _MUTEX_FAST if i
369b0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  t does.** not wa
369c0 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20  nt to.  ^SQLite 
369d0 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73  will only reques
369e0 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75  t a recursive mu
369f0 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20  tex in.** cases 
36a00 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20  where it really 
36a10 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20  needs one.  ^If 
36a20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63  a faster non-rec
36a30 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20  ursive mutex.** 
36a40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
36a50 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74  s available on t
36a60 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d  he host platform
36a70 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73  , the mutex subs
36a80 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72  ystem.** might r
36a90 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74  eturn such a mut
36aa0 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ex in response t
36ab0 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  o SQLITE_MUTEX_F
36ac0 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  AST..**.** ^The 
36ad0 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61  other allowed pa
36ae0 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69  rameters to sqli
36af0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36b00 29 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  ) (anything othe
36b10 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45  r.** than SQLITE
36b20 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20  _MUTEX_FAST and 
36b30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36b40 55 52 53 49 56 45 29 20 65 61 63 68 20 72 65 74  URSIVE) each ret
36b50 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
36b60 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
36b70 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
36b80 20 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75 74   ^Six static mut
36b90 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  exes are.** used
36ba0 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
36bb0 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
36bc0 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  e.  Future versi
36bd0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
36be0 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f   may add additio
36bf0 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
36c00 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65  es.  Static mute
36c10 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65  xes are for inte
36c20 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
36c30 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70  QLite only.  App
36c40 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
36c50 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65  se SQLite mutexe
36c60 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20  s should.** use 
36c70 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63  only the dynamic
36c80 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65   mutexes returne
36c90 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45  d by SQLITE_MUTE
36ca0 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c  X_FAST or.** SQL
36cb0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36cc0 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  IVE..**.** ^Note
36cd0 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
36ce0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
36cf0 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
36d00 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
36d10 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
36d20 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
36d30 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
36d40 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
36d50 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
36d60 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
36d70 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42   every call.  ^B
36d80 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69  ut for the stati
36d90 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73  c.** mutex types
36da0 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
36db0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
36dc0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
36dd0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
36de0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
36df0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36e00 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75  mutex_free() rou
36e10 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73  tine deallocates
36e20 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a   a previously.**
36e30 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d   allocated dynam
36e40 69 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69  ic mutex.  ^SQLi
36e50 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f  te is careful to
36e60 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72   deallocate ever
36e70 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74  y.** dynamic mut
36e80 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63  ex that it alloc
36e90 61 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d  ates.  The dynam
36ea0 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20  ic mutexes must 
36eb0 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65  not be in.** use
36ec0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64   when they are d
36ed0 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74  eallocated.  Att
36ee0 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c  empting to deall
36ef0 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a  ocate a static.*
36f00 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20  * mutex results 
36f10 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
36f20 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20  avior.  ^SQLite 
36f30 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65  never deallocate
36f40 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75  s.** a static mu
36f50 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tex..**.** ^The 
36f60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
36f70 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ter() and sqlite
36f80 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f  3_mutex_try() ro
36f90 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a  utines attempt.*
36fa0 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74  * to enter a mut
36fb0 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72  ex.  ^If another
36fc0 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61   thread is alrea
36fd0 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75  dy within the mu
36fe0 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  tex,.** sqlite3_
36ff0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69  mutex_enter() wi
37000 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c  ll block and sql
37010 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
37020 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
37030 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54  SQLITE_BUSY.  ^T
37040 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
37050 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  _try() interface
37060 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
37070 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63  _OK].** upon suc
37080 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20  cessful entry.  
37090 5e 28 4d 75 74 65 78 65 73 20 63 72 65 61 74 65  ^(Mutexes create
370a0 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  d using.** SQLIT
370b0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
370c0 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64  E can be entered
370d0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
370e0 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
370f0 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63  ad..** In such c
37100 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74  ases the,.** mut
37110 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65  ex must be exite
37120 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65  d an equal numbe
37130 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72  r of times befor
37140 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  e another thread
37150 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e  .** can enter.)^
37160 20 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20    ^(If the same 
37170 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20  thread tries to 
37180 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a  enter any other.
37190 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78  ** kind of mutex
371a0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
371b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
371c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53   undefined..** S
371d0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
371e0 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
371f0 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
37200 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
37210 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53  xes.)^.**.** ^(S
37220 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72  ome systems (for
37230 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77   example, Window
37240 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70  s 95) do not sup
37250 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69  port the operati
37260 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65  on.** implemente
37270 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74  d by sqlite3_mut
37280 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68  ex_try().  On th
37290 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c  ose systems, sql
372a0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
372b0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  .** will always 
372c0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
372d0 53 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  SY.  The SQLite 
372e0 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75  core only ever u
372f0 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ses.** sqlite3_m
37300 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e  utex_try() as an
37310 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f   optimization so
37320 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61   this is accepta
37330 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a  ble behavior.)^.
37340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37350 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
37360 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61   routine exits a
37370 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a   mutex that was.
37380 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e  ** previously en
37390 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d  tered by the sam
373a0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68  e thread.   ^(Th
373b0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
373c0 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68   undefined if th
373d0 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63  e mutex is not c
373e0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
373f0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69   by the.** calli
37400 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20  ng thread or is 
37410 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c  not currently al
37420 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65  located.  SQLite
37430 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64   will.** never d
37440 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a  o either.)^.**.*
37450 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65  * ^If the argume
37460 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
37470 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c  tex_enter(), sql
37480 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
37490 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  , or.** sqlite3_
374a0 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73  mutex_leave() is
374b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
374c0 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20   then all three 
374d0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61  routines.** beha
374e0 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ve as no-ops..**
374f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
37500 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
37510 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
37520 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
37530 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
37540 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
37550 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
37560 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
37570 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
37580 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
37590 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
375a0 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
375b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
375c0 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
375d0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
375e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
375f0 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
37600 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37610 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f  REF: Mutex Metho
37620 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
37630 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
37640 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65  his structure de
37650 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65  fines the low-le
37660 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  vel routines.** 
37670 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65  used to allocate
37680 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73   and use mutexes
37690 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c  ..**.** Usually,
376a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
376b0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
376c0 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53  ns provided by S
376d0 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66  QLite are.** suf
376e0 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72  ficient, however
376f0 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68   the user has th
37700 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73  e option of subs
37710 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f  tituting a custo
37720 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  m.** implementat
37730 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69  ion for speciali
37740 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20  zed deployments 
37750 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77  or systems for w
37760 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64  hich SQLite.** d
37770 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
37780 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
37790 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68  mentation. In th
377a0 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65  is case, the use
377b0 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64  r.** creates and
377c0 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e   populates an in
377d0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
377e0 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73  tructure to pass
377f0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
37800 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69  onfig() along wi
37810 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  th the [SQLITE_C
37820 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
37830 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ion..** Addition
37840 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63  ally, an instanc
37850 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
37860 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
37870 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20  as an.** output 
37880 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75  variable when qu
37890 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65  erying the syste
378a0 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  m for the curren
378b0 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  t mutex.** imple
378c0 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67  mentation, using
378d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
378e0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70  FIG_GETMUTEX] op
378f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
37900 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
37910 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
37920 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
37930 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
37940 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69  rt of system ini
37950 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74  tialization by t
37960 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
37970 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
37980 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78  ..** ^The xMutex
37990 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20  Init routine is 
379a0 63 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20  calle by SQLite 
379b0 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72  exactly once for
379c0 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69   each.** effecti
379d0 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ve call to [sqli
379e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
379f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  ]..**.** ^The xM
37a00 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64  utexEnd method d
37a10 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
37a20 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f  tructure is invo
37a30 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ked as.** part o
37a40 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77  f system shutdow
37a50 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  n by the sqlite3
37a60 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63  _shutdown() func
37a70 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70  tion. The.** imp
37a80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37a90 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78  his method is ex
37aa0 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73  pected to releas
37ab0 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e  e all outstandin
37ac0 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f  g.** resources o
37ad0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d  btained by the m
37ae0 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70  utex methods imp
37af0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70  lementation, esp
37b00 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65  ecially.** those
37b10 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65   obtained by the
37b20 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
37b30 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78  od.  ^The xMutex
37b40 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  End().** interfa
37b50 63 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78  ce is invoked ex
37b60 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65  actly once for e
37b70 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
37b80 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
37b90 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65  ..**.** ^(The re
37ba0 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65  maining seven me
37bb0 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79  thods defined by
37bc0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
37bd0 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a  (xMutexAlloc,.**
37be0 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75   xMutexFree, xMu
37bf0 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78  texEnter, xMutex
37c00 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65  Try, xMutexLeave
37c10 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64  , xMutexHeld and
37c20 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c  .** xMutexNothel
37c30 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  d) implement the
37c40 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72   following inter
37c50 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76  faces (respectiv
37c60 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ely):.**.** <ul>
37c70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
37c80 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
37c90 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
37ca0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37cb0 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69  tex_free()] </li
37cc0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
37cd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
37ce0 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  r()] </li>.**   
37cf0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37d00 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69  utex_try()] </li
37d10 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
37d20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
37d30 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
37d40 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37d50 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c  utex_held()] </l
37d60 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37d70 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
37d80 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
37d90 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
37da0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
37db0 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70  ce is that the p
37dc0 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58  ublic sqlite3_XX
37dd0 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d  X functions enum
37de0 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20  erated.** above 
37df0 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
37e00 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  any invocations 
37e10 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c  that pass a NULL
37e20 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
37e30 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  .** of a valid m
37e40 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65  utex handle. The
37e50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37e60 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20   of the methods 
37e70 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  defined.** by th
37e80 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65  is structure are
37e90 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
37ea0 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73   handle this cas
37eb0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a  e, the results.*
37ec0 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e  * of passing a N
37ed0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
37ee0 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  ead of a valid m
37ef0 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20  utex handle are 
37f00 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e  undefined.** (i.
37f10 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61  e. it is accepta
37f20 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61  ble to provide a
37f30 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37f40 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20   that segfaults 
37f50 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73  if.** it is pass
37f60 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ed a NULL pointe
37f70 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  r)..**.** The xM
37f80 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f  utexInit() metho
37f90 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  d must be thread
37fa0 73 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20  safe.  ^It must 
37fb0 62 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a  be harmless to.*
37fc0 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49  * invoke xMutexI
37fd0 6e 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69  nit() mutiple ti
37fe0 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  mes within the s
37ff0 61 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20  ame process and 
38000 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72  without.** inter
38010 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  vening calls to 
38020 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65  xMutexEnd().  Se
38030 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
38040 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
38050 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73  xMutexInit() mus
38060 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  t be no-ops..**.
38070 2a 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29  ** ^xMutexInit()
38080 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51   must not use SQ
38090 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  Lite memory allo
380a0 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33  cation ([sqlite3
380b0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e  _malloc()].** an
380c0 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73  d its associates
380d0 29 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20  ).  ^Similarly, 
380e0 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75  xMutexAlloc() mu
380f0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
38100 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
38110 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61  cation for a sta
38120 74 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77  tic mutex.  ^How
38130 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63  ever xMutexAlloc
38140 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74  () may use SQLit
38150 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
38160 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73  cation for a fas
38170 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d  t or recursive m
38180 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  utex..**.** ^SQL
38190 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
381a0 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20  the xMutexEnd() 
381b0 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c  method when [sql
381c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
381d0 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62   is.** called, b
381e0 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  ut only if the p
381f0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75  rior call to xMu
38200 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64  texInit returned
38210 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
38220 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69  f xMutexInit fai
38230 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69  ls in any way, i
38240 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f  t is expected to
38250 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20   clean up after 
38260 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20  itself.** prior 
38270 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f  to returning..*/
38280 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
38290 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
382a0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75  thods sqlite3_mu
382b0 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  tex_methods;.str
382c0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
382d0 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  x_methods {.  in
382e0 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28  t (*xMutexInit)(
382f0 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  void);.  int (*x
38300 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b  MutexEnd)(void);
38310 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  .  sqlite3_mutex
38320 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29   *(*xMutexAlloc)
38330 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a  (int);.  void (*
38340 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69  xMutexFree)(sqli
38350 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
38360 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74  void (*xMutexEnt
38370 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  er)(sqlite3_mute
38380 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
38390 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33  utexTry)(sqlite3
383a0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
383b0 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29  d (*xMutexLeave)
383c0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
383d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
383e0 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d  xHeld)(sqlite3_m
383f0 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28  utex *);.  int (
38400 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28  *xMutexNotheld)(
38410 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
38420 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
38430 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69  3REF: Mutex Veri
38440 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  fication Routine
38450 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
38460 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
38470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
38480 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75  ex_notheld() rou
38490 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74  tines.** are int
384a0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
384b0 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74  side assert() st
384c0 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
384d0 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e  SQLite core.** n
384e0 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20  ever uses these 
384f0 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20  routines except 
38500 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74  inside an assert
38510 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69  () and applicati
38520 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73  ons.** are advis
38530 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65  ed to follow the
38540 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72   lead of the cor
38550 65 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20  e.  ^The SQLite 
38560 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
38570 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
38580 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
38590 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
385a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
385b0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
385c0 44 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78  DEBUG flag.  ^Ex
385d0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70  ternal mutex imp
385e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
385f0 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65  are only require
38600 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65  d to provide the
38610 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53  se routines if S
38620 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a  QLITE_DEBUG is.*
38630 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66  * defined and if
38640 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64   NDEBUG is not d
38650 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
38660 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
38670 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65  ould return true
38680 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e   if the mutex in
38690 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a   their argument.
386a0 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f  ** is held or no
386b0 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69  t held, respecti
386c0 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c  vely, by the cal
386d0 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a  ling thread..**.
386e0 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ** ^The implemen
386f0 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65  tation is not re
38700 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
38710 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ed versions of t
38720 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hese.** routines
38730 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77   that actually w
38740 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c  ork. If the impl
38750 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
38760 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b  not provide work
38770 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ing.** versions 
38780 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
38790 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20  s, it should at 
387a0 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
387b0 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a  ubs that always.
387c0 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  ** return true s
387d0 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20  o that one does 
387e0 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73  not get spurious
387f0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75   assertion failu
38800 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  res..**.** ^If t
38810 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
38820 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
38830 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
38840 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
38850 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
38860 20 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69   return 1.   Thi
38870 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
38880 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
38890 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
388a0 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
388b0 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
388c0 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
388d0 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
388e0 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
388f0 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
38900 61 75 73 65 20 74 68 65 20 62 75 69 6c