/ Hex Artifact Content
Login

Artifact 6e91727c0c3f9e1365e8fea2b07369a09830f47f:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
90d0: 71 6c 69 74 65 33 5f 73 68 6d 20 73 71 6c 69 74  qlite3_shm sqlit
90e0: 65 33 5f 73 68 6d 3b 0a 73 74 72 75 63 74 20 73  e3_shm;.struct s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9100: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9110: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9120: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9130: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9140: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
9150: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9160: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9170: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9180: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9190: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
91a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9200: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9210: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9220: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9230: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9240: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9250: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9260: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9270: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9280: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9290: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
92a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9300: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9310: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9320: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9330: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9350: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9360: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9370: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9380: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9390: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
93a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9400: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9420: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9430: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9440: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9450: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9460: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9470: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
9580: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9590: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
95a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
95b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
95c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
95d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
95e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
95f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
9610: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9620: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9630: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
9640: 68 6d 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  hm**);.  int (*x
9650: 53 68 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ShmSize)(sqlite3
9660: 5f 73 68 6d 2a 2c 20 69 6e 74 20 72 65 71 53 69  _shm*, int reqSi
9670: 7a 65 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a  ze, int *pNewSiz
9680: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  e);.  int (*xShm
9690: 47 65 74 29 28 73 71 6c 69 74 65 33 5f 73 68 6d  Get)(sqlite3_shm
96a0: 2a 2c 20 69 6e 74 20 72 65 71 4d 61 70 53 69 7a  *, int reqMapSiz
96b0: 65 2c 20 69 6e 74 20 2a 70 4d 61 70 53 69 7a 65  e, int *pMapSize
96c0: 2c 20 76 6f 69 64 2a 2a 29 3b 0a 20 20 69 6e 74  , void**);.  int
96d0: 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29 28   (*xShmRelease)(
96e0: 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a 20  sqlite3_shm*);. 
96f0: 20 69 6e 74 20 28 2a 78 53 68 6d 50 75 73 68 29   int (*xShmPush)
9700: 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a  (sqlite3_shm*);.
9710: 20 20 69 6e 74 20 28 2a 78 53 68 6d 50 75 6c 6c    int (*xShmPull
9720: 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b  )(sqlite3_shm*);
9730: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
9740: 6b 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c  k)(sqlite3_shm*,
9750: 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b   int desiredLock
9760: 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b  , int *gotLock);
9770: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f  .  int (*xShmClo
9780: 73 65 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a  se)(sqlite3_shm*
9790: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 44  );.  int (*xShmD
97a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
97b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
97c0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 69 6e 74 20 28  *zName);.  int (
97d0: 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
97e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
97f0: 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73 74 20  ar *zOld, const 
9800: 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69 6e 74 20  char *zNew, int 
9810: 64 69 72 53 79 6e 63 29 3b 0a 20 20 69 6e 74 20  dirSync);.  int 
9820: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
9830: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
9840: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9850: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
9860: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
9870: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
9880: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
9890: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
98a0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
98b0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
98c0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
98d0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
98e0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
98f0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
9900: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
9910: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
9920: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9930: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9940: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
9950: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
9960: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9970: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9980: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
9990: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
99a0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
99b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
99c0: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
99d0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
99e0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
99f0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9a00: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9a10: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
9a20: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
9a30: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
9a40: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
9a50: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9a60: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
9a70: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9a80: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
9a90: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9aa0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
9ab0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9ac0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9ad0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
9ae0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9af0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
9b00: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9b10: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9b20: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
9b30: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9b40: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9b50: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9b60: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9b70: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9b80: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9b90: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
9ba0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9bb0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
9bc0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
9bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
9be0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
9bf0: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
9c00: 73 20 6c 6f 63 6b 69 6e 67 20 73 74 61 74 65 73  s locking states
9c10: 20 74 68 61 74 0a 2a 2a 20 61 6e 20 73 71 6c 69   that.** an sqli
9c20: 74 65 33 5f 73 68 6d 20 6f 62 6a 65 63 74 20 63  te3_shm object c
9c30: 61 6e 20 62 65 20 69 6e 2e 20 20 54 68 65 20 53  an be in.  The S
9c40: 51 4c 49 54 45 5f 53 48 4d 5f 51 55 45 52 59 20  QLITE_SHM_QUERY 
9c50: 69 6e 74 65 67 65 72 0a 2a 2a 20 69 73 20 6e 6f  integer.** is no
9c60: 74 20 61 20 76 61 6c 69 64 20 64 61 74 61 20 2d  t a valid data -
9c70: 20 69 74 20 69 73 20 61 20 63 6f 6e 73 74 61 6e   it is a constan
9c80: 74 20 70 61 73 74 65 64 20 74 6f 20 74 68 65 20  t pasted to the 
9c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 66 73 2e  .** sqlite3_vfs.
9ca0: 78 53 68 6d 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  xShmLock() metho
9cb0: 64 20 66 6f 72 20 71 75 65 72 79 69 6e 67 20 74  d for querying t
9cc0: 68 65 20 63 75 72 72 65 6e 74 20 6c 6f 63 6b 0a  he current lock.
9cd0: 2a 2a 20 73 74 61 74 65 2e 0a 2a 2f 0a 23 64 65  ** state..*/.#de
9ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
9cf0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 30 0a 23  UNLOCK       0.#
9d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9d10: 4d 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 31  M_READ         1
9d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d30: 53 48 4d 5f 52 45 41 44 5f 46 55 4c 4c 20 20 20  SHM_READ_FULL   
9d40: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
9d50: 45 5f 53 48 4d 5f 57 52 49 54 45 20 20 20 20 20  E_SHM_WRITE     
9d60: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
9d70: 49 54 45 5f 53 48 4d 5f 50 45 4e 44 49 4e 47 20  ITE_SHM_PENDING 
9d80: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
9d90: 51 4c 49 54 45 5f 53 48 4d 5f 43 48 45 43 4b 50  QLITE_SHM_CHECKP
9da0: 4f 49 4e 54 20 20 20 35 0a 23 64 65 66 69 6e 65  OINT   5.#define
9db0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45 43 4f   SQLITE_SHM_RECO
9dc0: 56 45 52 20 20 20 20 20 20 36 0a 23 64 65 66 69  VER      6.#defi
9dd0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 51 55  ne SQLITE_SHM_QU
9de0: 45 52 59 20 20 20 20 20 20 20 20 28 2d 31 29 0a  ERY        (-1).
9df0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9e00: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
9e10: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
9e20: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
9e30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9e40: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
9e50: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
9e60: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
9e70: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9e80: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
9e90: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
9ea0: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
9eb0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
9ec0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9ed0: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
9ee0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
9ef0: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
9f00: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
9f10: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
9f20: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
9f30: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
9f40: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
9f50: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
9f60: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
9f70: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
9f80: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
9f90: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
9fa0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
9fb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9fc0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
9fd0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
9fe0: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
9ff0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
a000: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
a010: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
a020: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
a030: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
a040: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
a050: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
a060: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
a070: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
a080: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
a090: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a0a0: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
a0b0: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
a0c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a0d0: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
a0e0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
a0f0: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
a100: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
a110: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
a120: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
a130: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
a140: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
a150: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
a160: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
a170: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a180: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
a190: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
a1a0: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
a1b0: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
a1c0: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
a1d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
a1e0: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
a1f0: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
a200: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
a210: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
a220: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
a230: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
a240: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a250: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
a260: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
a270: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
a280: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
a290: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
a2a0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a2b0: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
a2c0: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
a2d0: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
a2e0: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
a2f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a300: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
a310: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
a320: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
a330: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
a340: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
a350: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
a360: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
a370: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
a380: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
a390: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
a3a0: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
a3b0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
a3c0: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
a3d0: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
a3e0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
a3f0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
a400: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
a410: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
a420: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
a430: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a440: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
a450: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
a460: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
a470: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
a480: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
a490: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
a4a0: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
a4b0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
a4c0: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
a4d0: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
a4e0: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
a4f0: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
a500: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
a510: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
a520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
a530: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a540: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
a550: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
a560: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
a570: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
a580: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
a590: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
a5a0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
a5b0: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
a5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
a5d0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
a5e0: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
a5f0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
a600: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a610: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
a620: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
a630: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
a640: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
a650: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
a660: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
a670: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
a680: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
a690: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
a6a0: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
a6b0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a6c0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
a6d0: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
a6e0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
a6f0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
a700: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
a710: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a720: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
a730: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
a740: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
a750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a760: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
a770: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
a780: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
a790: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
a7a0: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
a7b0: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
a7c0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
a7d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
a7e0: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
a7f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a800: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
a810: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a820: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a830: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
a840: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
a850: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
a860: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
a870: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
a880: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
a890: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
a8a0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a8b0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
a8c0: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
a8d0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
a8e0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
a8f0: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
a900: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
a910: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a920: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
a930: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
a940: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
a950: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
a960: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
a970: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
a980: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a990: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
a9a0: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
a9b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a9c0: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
a9d0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
a9e0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
a9f0: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
aa00: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
aa10: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
aa20: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
aa30: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
aa40: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
aa50: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
aa60: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
aa70: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
aa80: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
aa90: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
aaa0: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
aab0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
aac0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
aad0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
aae0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
aaf0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ab00: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
ab10: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
ab20: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
ab30: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
ab40: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
ab50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ab60: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
ab70: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
ab80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ab90: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
aba0: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
abb0: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
abc0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
abd0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
abe0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
abf0: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
ac00: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
ac10: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
ac20: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
ac30: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
ac40: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ac50: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
ac60: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
ac70: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
ac80: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
ac90: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
aca0: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
acb0: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
acc0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
acd0: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
ace0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
acf0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
ad00: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
ad10: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
ad20: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
ad30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
ad40: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
ad50: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
ad60: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
ad70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
ad80: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
ad90: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
ada0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
adb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
adc0: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
add0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
ade0: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
adf0: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
ae00: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
ae10: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
ae20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
ae30: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ae40: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
ae50: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
ae60: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
ae70: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
ae80: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
ae90: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
aea0: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
aeb0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
aec0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
aed0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
aee0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
aef0: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
af00: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
af10: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
af20: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
af30: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
af40: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
af50: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
af60: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
af70: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
af80: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
af90: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
afa0: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
afb0: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
afc0: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
afd0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
afe0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
aff0: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
b000: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
b010: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
b020: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
b030: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
b040: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
b050: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
b060: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
b070: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
b080: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
b090: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
b0a0: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
b0b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
b0c0: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
b0d0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
b0e0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
b0f0: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
b100: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
b110: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b120: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
b130: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
b140: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
b150: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
b160: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
b170: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
b180: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
b190: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
b1a0: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
b1b0: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
b1c0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
b1d0: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
b1e0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
b1f0: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
b200: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
b210: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
b220: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
b230: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
b240: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
b250: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
b260: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
b270: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
b280: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
b290: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
b2a0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
b2b0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
b2c0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
b2d0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
b2e0: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
b2f0: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
b300: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
b310: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
b320: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
b330: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
b340: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
b350: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
b360: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
b370: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
b380: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
b390: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b3a0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
b3b0: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
b3c0: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
b3d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b3e0: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
b3f0: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
b400: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
b410: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
b420: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
b430: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
b440: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
b450: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
b460: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
b470: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
b480: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
b490: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b4a0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
b4b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
b4c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
b4d0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
b4e0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
b4f0: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
b500: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
b510: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
b520: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
b530: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
b540: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
b550: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b560: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
b570: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
b580: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
b590: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b5a0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
b5b0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b5c0: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
b5d0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b5e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  () interface sho
b5f0: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  uld only be used
b600: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
b610: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
b620: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
b630: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b640: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
b650: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
b660: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
b670: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
b680: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
b690: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
b6a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b6b0: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
b6c0: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
b6d0: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
b6e0: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
b6f0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
b700: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
b710: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b720: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
b730: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
b740: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
b750: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
b760: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
b770: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
b780: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
b790: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
b7a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
b7b0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
b7c0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
b7d0: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
b7e0: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
b7f0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
b800: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
b810: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
b820: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
b830: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
b840: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
b850: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
b860: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
b870: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
b880: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
b890: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
b8a0: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
b8b0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
b8c0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
b8d0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
b8e0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
b8f0: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
b900: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
b910: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b920: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
b930: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
b940: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
b950: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
b960: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
b970: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
b980: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
b990: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
b9a0: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
b9b0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
b9c0: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
b9d0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
b9e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
b9f0: 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
ba00: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
ba10: 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
ba20: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
ba30: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
ba40: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
ba50: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
ba60: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
ba70: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
ba80: 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
ba90: 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
baa0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
bab0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
bac0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
bad0: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
bae0: 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
baf0: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
bb00: 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
bb10: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
bb20: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
bb30: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
bb40: 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
bb50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
bb60: 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
bb70: 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
bb80: 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
bb90: 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
bba0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
bbb0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
bbc0: 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
bbd0: 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
bbe0: 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
bbf0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
bc00: 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
bc10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bc20: 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
bc30: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
bc40: 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
bc50: 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
bc60: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
bc70: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
bc80: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
bc90: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
bca0: 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
bcb0: 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
bcc0: 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
bcd0: 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
bce0: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
bcf0: 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
bd00: 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
bd10: 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
bd20: 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78  he xMalloc and x
bd30: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
bd40: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
bd50: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ** malloc() and 
bd60: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
bd70: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
bd80: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
bd90: 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65   The xRealloc me
bda0: 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c  thod must work l
bdb0: 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72  ike realloc() fr
bdc0: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
bdd0: 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74  C library.** wit
bde0: 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20  h the exception 
bdf0: 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f  that if the seco
be00: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  nd argument to x
be10: 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c  Realloc is zero,
be20: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73  .** xRealloc mus
be30: 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69  t be a no-op - i
be40: 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f  t must not perfo
be50: 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f  rm any allocatio
be60: 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  n or.** dealloca
be70: 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67  tion.  ^SQLite g
be80: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
be90: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
bea0: 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
beb0: 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
bec0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
bed0: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
bee0: 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64  xRoundup..** And
bef0: 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65   so in cases whe
bf00: 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61  re xRoundup alwa
bf10: 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ys returns a pos
bf20: 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a  itive number,.**
bf30: 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65   xRealloc can pe
bf40: 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73  rform exactly as
bf50: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
bf60: 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20  brary realloc() 
bf70: 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20  and.** still be 
bf80: 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69  in compliance wi
bf90: 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63  th this specific
bfa0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  ation..**.** xSi
bfb0: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
bfc0: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
bfd0: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
bfe0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
bff0: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
c000: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
c010: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
c020: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
c030: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
c040: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
c050: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
c060: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
c070: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
c080: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
c090: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
c0a0: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
c0b0: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
c0c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c0d0: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
c0e0: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
c0f0: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
c100: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
c110: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
c120: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
c130: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
c140: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
c150: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
c160: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
c170: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
c180: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
c190: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
c1a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c1b0: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
c1c0: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
c1d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
c1e0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
c1f0: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
c200: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
c210: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
c220: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
c230: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
c240: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
c250: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
c260: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
c270: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
c280: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
c290: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
c2a0: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
c2b0: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
c2c0: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
c2d0: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
c2e0: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
c2f0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
c300: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
c310: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
c320: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
c330: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
c340: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
c350: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
c360: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
c370: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
c380: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
c390: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
c3a0: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
c3b0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
c3c0: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
c3d0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
c3e0: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
c3f0: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
c400: 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
c410: 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
c420: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
c430: 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
c440: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
c450: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
c460: 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
c470: 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
c480: 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
c490: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
c4a0: 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
c4b0: 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
c4c0: 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
c4d0: 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
c4e0: 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
c4f0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
c500: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
c510: 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
c520: 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
c530: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c540: 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
c550: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
c560: 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
c570: 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
c580: 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
c590: 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
c5a0: 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
c5b0: 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
c5c0: 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
c5d0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
c5e0: 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
c5f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
c600: 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
c610: 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
c620: 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
c630: 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
c640: 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
c650: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
c660: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
c670: 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
c680: 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
c690: 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
c6a0: 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
c6b0: 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
c6c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c6d0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
c6e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c6f0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
c700: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
c710: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
c720: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
c730: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
c740: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
c750: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
c760: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c770: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
c780: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
c790: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
c7a0: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
c7b0: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
c7c0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c7d0: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
c7e0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c7f0: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
c800: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
c810: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
c820: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
c830: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
c840: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
c850: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
c860: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
c870: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
c880: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
c890: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
c8a0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
c8b0: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
c8c0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
c8d0: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
c8e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c8f0: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
c900: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
c910: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
c920: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
c930: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
c940: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
c950: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
c960: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
c970: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
c980: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
c990: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
c9a0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
c9b0: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
c9c0: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
c9d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
c9e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
c9f0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
ca00: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
ca10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ca20: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
ca30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
ca40: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
ca50: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
ca60: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
ca70: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
ca80: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
ca90: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
caa0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
cab0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
cac0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
cad0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
cae0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
caf0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
cb00: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
cb10: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
cb20: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
cb30: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
cb40: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
cb50: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
cb60: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
cb70: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
cb80: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
cb90: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
cba0: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
cbb0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
cbc0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
cbd0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
cbe0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
cbf0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
cc00: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
cc10: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
cc20: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
cc30: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
cc40: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
cc50: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
cc60: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
cc70: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
cc80: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
cc90: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
cca0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
ccb0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
ccc0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
ccd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
cce0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ccf0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
cd00: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
cd10: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
cd20: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
cd30: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
cd40: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
cd50: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
cd60: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
cd70: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
cd80: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
cd90: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
cda0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
cdb0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
cdc0: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
cdd0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
cde0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cdf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
ce00: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
ce10: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
ce20: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
ce30: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
ce40: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
ce50: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
ce60: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
ce70: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
ce80: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
ce90: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
cea0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
ceb0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
cec0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
ced0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
cee0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
cef0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
cf00: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
cf10: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
cf20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
cf30: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
cf40: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
cf50: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
cf60: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
cf70: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf80: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
cf90: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
cfa0: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
cfb0: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
cfc0: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
cfd0: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
cfe0: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
cff0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
d000: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
d010: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d020: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d030: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d040: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d050: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d060: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d070: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d080: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d090: 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
d0a0: 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
d0b0: 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
d0c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d0d0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
d0e0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
d0f0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
d100: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d110: 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
d120: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
d130: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d150: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
d160: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d170: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d180: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d190: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d1a0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d1b0: 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
d1c0: 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
d1d0: 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
d1e0: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
d1f0: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
d200: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
d210: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
d220: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d230: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
d240: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
d250: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
d260: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
d270: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
d280: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
d290: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
d2a0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
d2b0: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
d2c0: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
d2d0: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
d2e0: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
d2f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
d300: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
d310: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
d320: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
d330: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
d340: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
d350: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d360: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
d370: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
d380: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
d390: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
d3a0: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
d3b0: 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
d3c0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
d3d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
d3e0: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
d3f0: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
d400: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d410: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
d420: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
d430: 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
d440: 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
d450: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
d460: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
d470: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
d480: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
d490: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
d4a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d4b0: 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
d4c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
d4d0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d4e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d4f0: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
d500: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
d510: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d520: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d530: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d540: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d550: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
d560: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d570: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d580: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d590: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d5a0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
d5b0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
d5c0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
d5d0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
d5e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
d5f0: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
d600: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
d610: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
d620: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
d630: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
d640: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
d650: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
d660: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
d670: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
d680: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
d690: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
d6a0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d6b0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
d6c0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
d6d0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d6e0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
d6f0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
d700: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
d710: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
d720: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d730: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
d740: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
d750: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
d760: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
d770: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
d780: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
d790: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d7a0: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
d7b0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
d7c0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
d7d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
d7e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
d7f0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
d800: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
d810: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
d820: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
d830: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
d840: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
d850: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
d860: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d870: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d880: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
d890: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
d8a0: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
d8b0: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
d8c0: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
d8d0: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
d8e0: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
d8f0: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
d900: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
d910: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
d920: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
d930: 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
d940: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
d950: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
d960: 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
d970: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
d980: 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
d990: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
d9a0: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
d9b0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
d9c0: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
d9d0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
d9e0: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
d9f0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
da00: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
da10: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
da20: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
da30: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
da40: 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
da50: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
da60: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
da70: 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
da80: 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
da90: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
daa0: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
dab0: 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
dac0: 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
dad0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
dae0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
daf0: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
db00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
db10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
db20: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
db30: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
db40: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
db50: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
db60: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
db70: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
db80: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
db90: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
dba0: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
dbb0: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
dbc0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
dbd0: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
dbe0: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
dbf0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
dc00: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
dc10: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
dc20: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
dc30: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
dc40: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
dc50: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
dc60: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
dc70: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
dc80: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
dc90: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
dca0: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
dcb0: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
dcc0: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
dcd0: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
dce0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
dcf0: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
dd00: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
dd10: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
dd20: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
dd30: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
dd40: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
dd50: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
dd60: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
dd70: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
dd80: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
dd90: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
dda0: 62 75 66 66 65 72 20 70 65 72 20 74 68 72 65 61  buffer per threa
ddb0: 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
ddc0: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
ddd0: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
dde0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
ddf0: 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ads.  ^SQLite wi
de00: 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75  ll.** never requ
de10: 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
de20: 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
de30: 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74  e than 6 times t
de40: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
de50: 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
de60: 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
de70: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61   additional scra
de80: 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
de90: 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72  d .** what is pr
dea0: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
deb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
dec0: 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
ded0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
dee0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
def0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
df00: 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
df10: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
df20: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
df30: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
df40: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
df50: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
df60: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
df70: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
df80: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
df90: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
dfa0: 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
dfb0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
dfc0: 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  emenation.  .** 
dfd0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
dfe0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
dff0: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
e000: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
e010: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
e020: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
e030: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
e040: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
e050: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
e060: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e070: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e080: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
e090: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
e0a0: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
e0b0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
e0c0: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
e0d0: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
e0e0: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
e0f0: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
e100: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
e110: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
e120: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
e130: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
e140: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
e150: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
e160: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
e170: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
e180: 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
e190: 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
e1a0: 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
e1b0: 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
e1c0: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
e1d0: 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
e1e0: 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
e1f0: 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
e200: 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
e210: 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
e220: 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
e230: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
e240: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
e250: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
e260: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
e270: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
e280: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
e290: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
e2a0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
e2b0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e2c0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
e2d0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
e2e0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
e2f0: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
e300: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
e310: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
e320: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
e330: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
e340: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e350: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
e360: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
e370: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
e380: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
e390: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
e3a0: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
e3b0: 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  .** ^The impleme
e3c0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73  ntation might us
e3d0: 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  e one or more of
e3e0: 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74   the N buffers t
e3f0: 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72  o hold .** memor
e400: 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66  y accounting inf
e410: 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f  ormation. The po
e420: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
e430: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
e440: 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
e450: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
e460: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
e470: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
e480: 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
e490: 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
e4a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e4b0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
e4c0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e4d0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
e4e0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
e4f0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
e500: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
e510: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
e520: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
e530: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
e540: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
e550: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
e560: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
e570: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
e580: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
e590: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
e5a0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
e5b0: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
e5c0: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
e5d0: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
e5e0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
e5f0: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
e600: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
e610: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
e620: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
e630: 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
e640: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
e650: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
e660: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
e670: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
e680: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
e690: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e6a0: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
e6b0: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
e6c0: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
e6d0: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
e6e0: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
e6f0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
e700: 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
e710: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
e720: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
e730: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
e740: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
e750: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
e760: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
e770: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
e780: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
e790: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
e7a0: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
e7b0: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
e7c0: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
e7d0: 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
e7e0: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
e7f0: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
e800: 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
e810: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
e820: 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
e830: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
e840: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
e850: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
e860: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
e870: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e880: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
e890: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
e8a0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
e8b0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
e8c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
e8d0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
e8e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
e8f0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
e900: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
e910: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
e920: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
e930: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
e940: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e950: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
e960: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
e970: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
e980: 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
e990: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
e9a0: 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
e9b0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
e9c0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
e9d0: 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
e9e0: 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
e9f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ea00: 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
ea10: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ea20: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ea30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ea40: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ea50: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ea60: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ea70: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
ea80: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
ea90: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
eaa0: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
eab0: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
eac0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ead0: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
eae0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
eaf0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
eb00: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
eb10: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
eb20: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
eb30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
eb40: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
eb50: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
eb60: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
eb70: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
eb80: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
eb90: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
eba0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
ebb0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ebc0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ebd0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
ebe0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
ebf0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
ec00: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
ec10: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
ec20: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
ec30: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
ec40: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
ec50: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
ec60: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
ec70: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
ec80: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
ec90: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
eca0: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
ecb0: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
ecc0: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
ecd0: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
ece0: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
ecf0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ed00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
ed10: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
ed20: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
ed30: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ed40: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
ed50: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
ed60: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
ed70: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
ed80: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
ed90: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
eda0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
edb0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
edc0: 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
edd0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ede0: 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
edf0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
ee00: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
ee10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
ee20: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
ee30: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
ee40: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
ee50: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
ee60: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
ee70: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ee80: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
ee90: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
eea0: 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
eeb0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
eec0: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
eed0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
eee0: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
eef0: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
ef00: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
ef10: 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
ef20: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
ef30: 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
ef40: 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
ef50: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
ef60: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
ef70: 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
ef80: 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
ef90: 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
efa0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
efb0: 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
efc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
efd0: 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
efe0: 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
eff0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
f000: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
f010: 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
f020: 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
f030: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f040: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
f050: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f060: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f070: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f080: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f090: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
f0a0: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f0b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
f0c0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
f0d0: 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
f0e0: 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
f0f0: 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
f100: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
f110: 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
f120: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
f130: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
f140: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f150: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f160: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f170: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f180: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f190: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f1a0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f1b0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f1c0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f1d0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
f1e0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f1f0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53  hods] object.  S
f200: 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
f210: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
f220: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
f230: 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
f240: 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
f250: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f260: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
f270: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
f280: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f290: 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
f2a0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
f2b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
f2c0: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
f2d0: 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
f2e0: 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
f2f0: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
f300: 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
f310: 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
f320: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
f330: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
f340: 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
f350: 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
f360: 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
f370: 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
f380: 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
f390: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
f3a0: 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
f3b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
f3c0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
f3d0: 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
f3e0: 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
f3f0: 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
f400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
f410: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f420: 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
f430: 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
f440: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
f450: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f460: 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
f470: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
f480: 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
f490: 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
f4a0: 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
f4b0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f4c0: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
f4d0: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
f4e0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f4f0: 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
f500: 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
f510: 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
f520: 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
f530: 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
f540: 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
f550: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
f560: 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
f570: 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
f580: 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
f590: 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
f5a0: 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
f5b0: 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
f5c0: 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
f5d0: 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
f5e0: 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
f5f0: 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
f600: 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
f610: 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
f620: 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
f630: 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
f640: 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
f650: 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
f660: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
f670: 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
f680: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
f690: 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
f6a0: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
f6b0: 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
f6c0: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
f6d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f6e0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
f6f0: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
f700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f710: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
f720: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
f730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f740: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
f750: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
f760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f770: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
f780: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
f790: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f7a0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f7b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f7c0: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
f7d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f7e0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f7f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
f800: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
f810: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
f820: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
f830: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f840: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
f850: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
f860: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
f870: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f880: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
f890: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
f8a0: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
f8b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f8c0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
f8d0: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
f8e0: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
f8f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
f900: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
f910: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f920: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f930: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f940: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
f950: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
f960: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
f970: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
f980: 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
f990: 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
f9a0: 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
f9b0: 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
f9c0: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
f9d0: 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
f9e0: 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
f9f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
fa00: 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
fa10: 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
fa20: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
fa30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
fa40: 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
fa50: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  5  /* sqlite3_pc
fa60: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
fa70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fa80: 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
fa90: 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
faa0: 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  , void* */../*.*
fab0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
fac0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
fad0: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
fae0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
faf0: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
fb00: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
fb10: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
fb20: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
fb30: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
fb40: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
fb50: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
fb60: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
fb70: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
fb80: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
fb90: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
fba0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
fbb0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
fbc0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
fbd0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
fbe0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
fbf0: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
fc00: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
fc10: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
fc20: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
fc30: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
fc40: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
fc50: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
fc60: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
fc70: 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
fc80: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
fc90: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
fca0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
fcb0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
fcc0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
fcd0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
fce0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
fcf0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
fd00: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
fd10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
fd20: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
fd30: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
fd40: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
fd50: 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
fd60: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
fd70: 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
fd80: 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
fd90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
fda0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
fdb0: 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
fdc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
fdd0: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
fde0: 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
fdf0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
fe00: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fe10: 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
fe20: 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20  er to an memory 
fe30: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
fe40: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
fe50: 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
fe60: 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
fe70: 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
fe80: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
fe90: 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
fea0: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
feb0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
fec0: 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
fed0: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
fee0: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
fef0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
ff00: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
ff10: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
ff20: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
ff30: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
ff40: 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
ff50: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
ff60: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
ff70: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
ff80: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
ff90: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ffa0: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
ffb0: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
ffc0: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
ffd0: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
ffe0: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
fff0: 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
10000 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
10010 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
10020 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
10030 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10040 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
10050 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10060 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
10070 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
10080 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
10090 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
100a0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
100b0 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
100c0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
100d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
100e0 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
100f0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
10100 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
10110 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
10120 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
10130 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
10140 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
10150 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
10160 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
10170 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
10180 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
10190 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
101a0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
101b0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
101c0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
101d0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
101e0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
101f0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
10200 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
10210 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
10220 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
10230 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
10240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
10250 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
10260 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
10270 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
10280 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
10290 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
102a0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
102b0 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
102c0 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
102d0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
102e0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
102f0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
10300 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
10310 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
10320 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
10330 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
10340 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
10350 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
10360 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
10370 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
10380 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
10390 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
103a0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
103b0 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
103c0 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
103d0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
103e0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
103f0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
10400 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
10410 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
10420 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
10430 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
10440 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
10450 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
10460 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
10470 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
10480 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
10490 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
104a0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
104b0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
104c0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
104d0 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
104e0 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
104f0 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
10500 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
10510 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
10520 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
10530 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
10540 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
10550 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
10560 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
10570 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
10580 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
10590 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
105a0 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
105b0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
105c0 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
105d0 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
105e0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
105f0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
10600 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
10610 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
10620 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
10630 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  ger fired.)^.**.
10640 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
10650 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
10660 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
10670 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
10680 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
10690 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
106a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
106b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
106c0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
106d0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
106e0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
106f0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
10700 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
10710 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
10720 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
10730 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
10740 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
10750 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
10760 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
10770 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
10780 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
10790 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
107a0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
107b0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
107c0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
107d0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
107e0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
107f0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
10800 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
10810 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
10820 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
10830 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
10840 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
10850 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
10860 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10870 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
10880 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
10890 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
108a0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
108b0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
108c0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
108d0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
108e0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
108f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
10900 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
10910 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
10920 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
10930 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
10940 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
10950 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
10960 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
10970 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
10980 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
10990 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
109a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
109b0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
109c0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
109d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
109e0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
109f0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
10a00 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
10a10 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
10a20 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
10a30 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
10a40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10a50 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
10a60 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
10a70 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10a80 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10a90 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10aa0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
10ab0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
10ac0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
10ad0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10ae0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
10af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
10b00 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
10b10 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
10b20 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
10b30 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
10b40 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
10b50 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
10b60 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
10b70 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
10b80 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
10b90 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
10ba0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
10bb0 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
10bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10bd0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
10be0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10bf0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
10c00 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
10c10 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
10c20 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
10c30 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
10c40 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
10c50 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
10c60 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
10c70 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
10c80 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
10c90 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
10ca0 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
10cb0 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
10cc0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
10cd0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
10ce0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
10cf0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
10d00 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
10d10 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
10d20 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
10d30 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
10d40 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
10d50 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
10d60 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
10d70 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
10d80 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
10d90 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
10da0 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
10db0 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
10dc0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
10dd0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
10de0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
10df0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
10e00 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
10e10 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
10e20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
10e30 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
10e40 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
10e50 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
10e60 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
10e70 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
10e80 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
10e90 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
10ea0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
10eb0 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
10ec0 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
10ed0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
10ee0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
10ef0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
10f00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
10f10 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
10f20 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
10f30 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
10f40 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
10f50 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
10f60 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
10f70 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
10f80 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
10f90 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
10fa0 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
10fb0 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
10fc0 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
10fd0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
10fe0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
10ff0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
11000 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
11010 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
11020 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
11030 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
11040 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
11050 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
11060 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
11070 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
11080 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
11090 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
110a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
110b0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
110c0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
110d0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
110e0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
110f0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
11100 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
11110 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
11120 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
11130 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
11140 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
11150 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
11160 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
11170 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
11180 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
11190 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
111a0 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
111b0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
111c0 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
111d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
111e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
111f0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
11200 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
11210 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
11220 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
11230 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
11240 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
11250 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
11260 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
11270 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
11280 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
11290 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
112a0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
112b0 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
112c0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
112d0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
112e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
112f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
11300 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
11310 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
11320 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
11330 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
11340 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
11350 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
11360 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
11370 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
11380 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
11390 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
113a0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
113b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
113c0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
113d0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
113e0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
113f0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
11400 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
11410 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
11420 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
11430 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
11440 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
11450 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11460 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
11470 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11480 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
11490 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
114a0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
114b0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
114c0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
114d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
114e0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
114f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11500 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
11510 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
11520 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11530 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11540 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
11550 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
11560 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
11570 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
11580 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
11590 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
115a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
115b0 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
115c0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
115d0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
115e0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
115f0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
11600 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
11610 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
11620 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
11630 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
11640 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
11650 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
11660 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
11670 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
11680 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
11690 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
116a0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
116b0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
116c0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
116d0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
116e0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
116f0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
11700 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
11710 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
11720 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
11730 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
11740 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
11750 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
11760 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
11770 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
11780 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
11790 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
117a0 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
117b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
117c0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
117d0 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
117e0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
117f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
11800 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
11810 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
11820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
11830 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
11840 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
11850 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
11860 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
11870 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
11880 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
11890 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
118a0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
118b0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
118c0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
118d0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
118e0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
118f0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
11900 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
11910 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
11920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11930 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
11940 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11950 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11960 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11970 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
11980 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
11990 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
119a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
119b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
119c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
119d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
119e0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
119f0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
11a00 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
11a10 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
11a20 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
11a30 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
11a40 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
11a50 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
11a60 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
11a70 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
11a80 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
11a90 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
11aa0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
11ab0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
11ac0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
11ad0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
11ae0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
11af0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
11b00 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
11b10 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
11b20 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
11b30 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
11b40 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
11b50 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
11b60 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
11b70 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
11b80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
11b90 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
11ba0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
11bb0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
11bc0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
11bd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11be0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
11bf0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
11c00 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
11c10 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
11c20 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
11c30 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
11c40 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
11c50 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
11c60 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
11c70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11c80 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
11c90 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
11ca0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
11cb0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
11cc0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
11cd0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
11ce0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
11cf0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
11d00 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
11d10 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
11d20 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
11d30 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
11d40 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
11d50 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
11d60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11d70 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
11d80 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
11d90 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
11da0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
11db0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
11dc0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
11dd0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
11de0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
11df0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
11e00 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
11e10 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
11e20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
11e30 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
11e40 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
11e50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e60 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
11e70 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
11e80 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
11e90 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
11ea0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11eb0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
11ec0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
11ed0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
11ee0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
11ef0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
11f00 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
11f10 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
11f20 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
11f30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11f40 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
11f50 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
11f60 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
11f70 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
11f80 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
11f90 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
11fa0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
11fb0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
11fc0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
11fd0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
11fe0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
11ff0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
12000 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
12010 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
12020 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
12030 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
12040 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
12050 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
12060 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12070 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12080 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
12090 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
120a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
120b0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
120c0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
120d0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
120e0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
120f0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
12100 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
12110 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
12120 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
12130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12140 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
12150 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
12160 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
12170 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12180 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
12190 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
121a0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
121b0 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
121c0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
121d0 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
121e0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
121f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
12200 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
12210 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
12220 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
12230 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
12240 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
12250 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
12260 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
12270 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
12280 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
12290 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
122a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
122b0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
122c0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
122d0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
122e0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
122f0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
12300 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
12310 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
12320 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
12330 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
12340 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
12350 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
12360 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
12370 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
12380 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
12390 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
123a0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
123b0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
123c0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
123d0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
123e0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
123f0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
12400 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
12410 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
12420 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
12430 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
12440 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
12450 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
12460 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
12470 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
12480 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
12490 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
124a0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
124b0 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
124c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
124d0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
124e0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
124f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
12500 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
12510 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
12520 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
12530 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
12540 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
12550 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
12560 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
12570 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
12580 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
12590 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
125a0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
125b0 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
125c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
125d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
125e0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
125f0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
12600 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
12610 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
12620 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
12630 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
12640 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
12650 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
12660 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
12670 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
12680 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
12690 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
126a0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
126b0 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
126c0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
126d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
126e0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
126f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
12700 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
12710 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
12720 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
12730 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
12740 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
12750 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
12760 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
12770 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
12780 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
12790 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
127a0 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
127b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
127c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
127d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
127e0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
127f0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
12800 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
12810 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
12820 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
12830 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
12840 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
12850 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
12860 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
12870 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
12880 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
12890 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
128a0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
128b0 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
128c0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
128d0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
128e0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
128f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
12900 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
12910 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
12920 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
12930 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
12940 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
12950 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
12960 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
12970 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
12980 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
12990 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
129a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
129b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
129c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
129d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
129e0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
129f0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
12a00 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
12a10 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
12a20 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
12a30 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12a40 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
12a50 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
12a60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
12a70 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
12a80 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
12a90 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
12aa0 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
12ab0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
12ac0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
12ad0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
12ae0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
12af0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
12b00 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
12b10 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
12b20 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
12b30 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12b40 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
12b50 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
12b60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
12b70 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
12b80 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
12b90 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
12ba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
12bb0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
12bc0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
12bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
12be0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
12bf0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
12c00 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
12c10 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
12c20 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
12c30 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
12c40 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
12c50 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
12c60 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
12c70 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
12c80 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
12c90 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
12ca0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
12cb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
12cc0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
12cd0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12ce0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
12cf0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
12d00 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
12d10 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
12d20 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
12d30 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
12d40 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
12d50 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
12d60 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
12d70 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
12d80 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
12d90 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
12da0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
12db0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
12dc0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
12dd0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
12de0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
12df0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
12e00 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
12e10 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
12e20 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
12e30 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
12e40 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
12e50 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
12e60 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
12e70 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
12e80 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
12e90 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
12ea0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
12eb0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
12ec0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
12ed0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
12ee0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
12ef0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
12f00 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
12f10 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
12f20 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
12f30 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
12f40 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
12f50 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
12f60 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
12f70 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
12f80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
12f90 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
12fa0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
12fb0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
12fc0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
12fd0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
12fe0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12ff0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
13000 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
13010 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
13020 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
13030 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
13040 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
13050 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
13060 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
13070 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
13080 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
13090 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
130a0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
130b0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
130c0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
130d0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
130e0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
130f0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
13100 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
13110 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
13120 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
13130 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
13140 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
13150 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
13160 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
13170 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
13180 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
13190 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
131a0 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
131b0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
131c0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
131d0 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
131e0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
131f0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
13200 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
13210 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13220 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
13230 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
13240 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
13250 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
13260 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
13270 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
13280 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
13290 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
132a0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
132b0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
132c0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
132d0 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
132e0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
132f0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
13300 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
13310 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
13320 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13330 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13340 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
13350 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13360 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
13370 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
13380 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
13390 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
133a0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
133b0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
133c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
133d0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
133e0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
133f0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
13400 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
13410 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
13420 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
13430 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
13440 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
13450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13460 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
13470 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13480 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
13490 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
134a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
134b0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
134c0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
134d0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
134e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
134f0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
13500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
13510 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
13520 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
13530 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
13540 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
13550 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
13560 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
13570 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
13580 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
13590 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
135a0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
135b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
135c0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
135d0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
135e0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
135f0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
13600 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
13610 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
13620 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
13630 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
13640 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
13650 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
13660 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13670 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
13680 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
13690 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
136a0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
136b0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
136c0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
136d0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
136e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
136f0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
13700 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
13710 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13720 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
13730 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
13740 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
13750 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
13760 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
13770 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
13780 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
13790 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
137a0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
137b0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
137c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
137d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
137e0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
137f0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
13800 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
13810 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
13820 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
13830 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
13840 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
13850 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
13860 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
13870 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
13880 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
13890 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
138a0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
138b0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
138c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
138d0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
138e0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
138f0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69  eries.**.** Defi
13900 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
13910 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
13920 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
13930 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
13940 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
13950 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
13960 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
13970 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
13980 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
13990 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
139a0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
139b0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
139c0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
139d0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
139e0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
139f0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
13a00 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
13a10 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
13a20 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
13a30 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
13a40 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
13a50 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
13a60 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
13a70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
13a80 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
13a90 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
13aa0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
13ab0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
13ac0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
13ad0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
13ae0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
13af0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
13b00 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
13b10 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
13b20 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
13b30 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
13b40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
13b50 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
13b60 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
13b70 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
13b80 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
13b90 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
13ba0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
13bb0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
13bc0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
13bd0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
13be0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
13bf0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
13c00 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
13c10 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
13c20 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
13c30 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
13c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
13c50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
13c60 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
13c70 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
13c80 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
13c90 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
13ca0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
13cb0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
13cc0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
13cd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
13ce0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
13cf0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
13d00 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
13d10 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
13d20 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
13d30 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
13d40 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
13d50 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
13d60 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
13d70 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
13d80 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
13d90 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
13da0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
13db0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
13dc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13dd0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
13de0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
13df0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
13e00 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
13e10 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
13e20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
13e30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
13e40 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
13e50 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
13e60 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
13e70 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
13e80 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
13e90 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
13ea0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
13eb0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
13ec0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
13ed0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
13ee0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
13ef0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
13f00 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
13f10 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13f20 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13f30 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
13f40 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13f50 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
13f60 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
13f70 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
13f80 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
13f90 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13fa0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
13fb0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13fc0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
13fd0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13fe0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
13ff0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14000 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
14010 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
14020 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
14030 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
14040 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14050 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
14060 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14070 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14080 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14090 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
140a0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
140b0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
140c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
140d0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
140e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
140f0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
14100 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
14110 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
14120 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
14130 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
14140 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
14150 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
14160 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
14170 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
14180 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
14190 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65   should pass the
141a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
141b0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
141c0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
141d0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
141e0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
141f0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
14200 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
14210 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
14220 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14230 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
14240 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14250 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
14260 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14270 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
14280 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
14290 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
142a0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
142b0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
142c0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
142d0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
142e0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
142f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
14300 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14310 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
14320 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
14330 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
14340 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14350 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
14360 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
14370 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
14380 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
14390 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
143a0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
143b0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
143c0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
143d0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
143e0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
143f0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
14400 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
14410 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
14420 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
14430 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
14440 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
14450 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
14460 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
14470 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
14480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
14490 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
144a0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e  te3_errmsg()].)^
144b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
144c0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
144d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
144e0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
144f0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
14500 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
14510 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
14520 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
14530 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
14540 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
14550 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
14560 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
14570 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
14580 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
14590 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
145a0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
145b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
145c0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
145d0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
145e0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
145f0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
14600 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
14610 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
14620 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
14630 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
14640 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
14650 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
14660 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
14670 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
14680 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
14690 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
146a0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
146b0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
146c0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
146d0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
146e0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
146f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
14700 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
14710 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
14720 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
14730 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
14740 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
14750 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14760 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
14770 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
14780 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
14790 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
147a0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
147b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
147c0 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
147d0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
147e0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
147f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
14800 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
14810 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
14820 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
14830 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
14840 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71  g..**.** ^(In sq
14850 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14860 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
14870 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
14880 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
14890 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
148a0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
148b0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
148c0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
148d0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
148e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
148f0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
14900 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
14910 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
14920 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
14930 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
14940 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
14950 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
14960 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
14970 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
14980 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
14990 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
149a0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
149b0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
149c0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
149d0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
149e0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
149f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
14a00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14a10 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
14a20 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
14a30 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
14a40 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
14a50 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
14a60 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
14a70 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
14a80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
14a90 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
14aa0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
14ab0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
14ac0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
14ad0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
14ae0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
14af0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14b00 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
14b10 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
14b20 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
14b30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
14b40 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
14b50 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
14b60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14b70 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
14b80 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
14b90 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
14ba0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
14bb0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
14bc0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
14bd0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
14be0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
14bf0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
14c00 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
14c10 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
14c20 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
14c30 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
14c40 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
14c50 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
14c60 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
14c70 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
14c80 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
14c90 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
14ca0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
14cb0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
14cc0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
14cd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
14ce0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
14cf0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
14d00 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
14d10 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
14d20 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
14d30 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
14d40 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
14d50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
14d60 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
14d70 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
14d80 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
14d90 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
14da0 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
14db0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
14dc0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
14dd0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
14de0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
14df0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
14e00 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
14e10 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
14e20 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
14e30 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
14e40 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
14e50 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
14e60 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
14e70 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
14e80 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
14e90 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
14ea0 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
14eb0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
14ec0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
14ed0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
14ee0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14ef0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14f00 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
14f10 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
14f20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14f30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
14f40 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
14f50 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
14f60 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
14f70 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14f80 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
14f90 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
14fa0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
14fb0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
14fc0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
14fd0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
14fe0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
14ff0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
15000 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
15010 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15020 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
15030 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
15040 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
15050 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
15060 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
15070 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
15080 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
15090 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
150a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
150b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
150c0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
150d0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
150e0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
150f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15100 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
15110 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
15120 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
15130 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
15140 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
15150 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
15160 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
15170 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15180 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
15190 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
151a0 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
151b0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
151c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
151d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
151e0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
151f0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
15200 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
15210 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
15220 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
15230 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
15240 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
15250 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
15260 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
15270 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
15280 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
15290 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
152a0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
152b0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
152c0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
152d0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
152e0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
152f0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
15300 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
15310 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
15320 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
15330 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
15340 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
15350 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
15360 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
15370 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
15380 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
15390 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
153a0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
153b0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
153c0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
153d0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
153e0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
153f0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
15400 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
15410 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
15420 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
15430 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15440 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
15450 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
15460 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
15470 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
15480 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
15490 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
154a0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
154b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
154c0 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
154d0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
154e0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
154f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
15500 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
15510 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
15520 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
15530 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
15540 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
15550 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
15560 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
15570 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
15580 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
15590 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
155a0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
155b0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
155c0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
155d0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
155e0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
155f0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
15600 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
15610 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
15620 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
15630 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
15640 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
15650 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
15660 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
15670 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
15680 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
15690 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
156a0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
156b0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
156c0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
156d0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
156e0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
156f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
15700 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
15710 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
15720 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
15730 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
15740 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
15750 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
15760 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
15770 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15780 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
15790 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
157a0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
157b0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
157c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
157d0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
157e0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
157f0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
15800 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
15810 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
15820 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
15830 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15840 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
15850 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
15860 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
15870 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
15880 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
15890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
158a0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
158b0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
158c0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
158d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
158e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
158f0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
15900 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
15910 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
15920 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
15930 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
15940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
15950 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
15960 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
15970 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
15980 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
15990 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
159a0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
159b0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
159c0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
159d0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
159e0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
159f0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
15a00 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
15a10 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
15a20 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
15a30 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
15a40 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
15a50 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
15a60 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
15a70 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
15a80 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
15a90 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
15aa0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
15ab0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
15ac0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
15ad0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
15ae0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
15af0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
15b00 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
15b10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15b20 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
15b30 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
15b40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
15b50 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
15b60 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
15b70 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
15b80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15b90 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
15ba0 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
15bb0 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
15bc0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
15bd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15be0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
15bf0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
15c00 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
15c10 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
15c20 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15c30 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
15c40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15c50 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
15c60 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
15c70 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
15c80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
15c90 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
15ca0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15cb0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15cc0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
15cd0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15ce0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
15cf0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
15d00 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
15d10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
15d20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
15d30 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
15d40 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
15d50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
15d60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15d70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15d80 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
15d90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
15da0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15db0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
15dc0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
15dd0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
15de0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
15df0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
15e00 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
15e10 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
15e20 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
15e30 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
15e40 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
15e50 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
15e60 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
15e70 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
15e80 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
15e90 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
15ea0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
15eb0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
15ec0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15ed0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
15ee0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
15ef0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
15f00 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
15f10 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
15f20 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
15f30 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
15f40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
15f50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
15f60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15f70 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
15f80 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
15f90 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
15fa0 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  ndary..**.** In 
15fb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
15fc0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
15fd0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
15fe0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
15ff0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
16000 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
16010 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
16020 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
16030 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16040 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
16050 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
16060 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
16070 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
16080 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
16090 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
160a0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
160b0 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
160c0 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
160d0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
160e0 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
160f0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
16100 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
16110 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
16120 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
16130 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
16140 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
16150 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
16160 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
16170 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
16180 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
16190 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
161a0 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
161b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
161c0 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
161d0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
161e0 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
161f0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
16200 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
16210 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
16220 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
16230 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
16240 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
16250 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
16260 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
16270 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
16280 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
16290 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
162a0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
162b0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
162c0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
162d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
162e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
162f0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
16300 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
16310 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
16320 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
16330 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
16340 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
16350 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
16360 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
16370 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
16380 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
16390 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
163a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
163b0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
163c0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
163d0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
163e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
163f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
16400 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
16410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16420 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
16430 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
16440 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
16450 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
16460 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
16470 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
16480 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
16490 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
164a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
164b0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
164c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
164d0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
164e0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
164f0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
16500 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
16510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
16520 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
16530 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
16540 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16550 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
16560 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
16570 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
16580 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
16590 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
165a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
165b0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
165c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
165d0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
165e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
165f0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
16600 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
16610 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
16620 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
16630 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
16640 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16650 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
16660 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16670 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
16680 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
16690 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
166a0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
166b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
166c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
166d0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
166e0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
166f0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
16700 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
16710 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
16720 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16730 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
16740 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
16750 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
16760 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
16770 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
16780 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
16790 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
167a0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
167b0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
167c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
167d0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
167e0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
167f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
16800 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16810 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
16820 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
16830 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
16840 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
16850 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
16860 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
16870 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
16880 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
16890 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
168a0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
168b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
168c0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
168d0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
168e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
168f0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
16900 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
16910 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
16920 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
16930 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
16940 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
16950 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
16960 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
16970 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
16980 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
16990 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
169a0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
169b0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
169c0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
169d0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
169e0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
169f0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
16a00 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
16a10 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
16a20 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
16a30 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
16a40 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
16a50 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
16a60 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
16a70 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
16a80 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
16a90 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
16aa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16ab0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
16ac0 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
16ad0 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
16ae0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
16af0 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
16b00 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
16b10 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
16b20 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
16b30 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
16b40 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
16b50 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
16b60 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
16b70 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
16b80 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
16b90 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
16ba0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
16bb0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
16bc0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
16bd0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
16be0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
16bf0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
16c00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
16c10 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
16c20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
16c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
16c40 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
16c50 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
16c60 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
16c70 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
16c80 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
16c90 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
16ca0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
16cb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16cc0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
16cd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16ce0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
16cf0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16d00 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
16d10 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
16d20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
16d30 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
16d40 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
16d50 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
16d60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
16d70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16d80 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
16d90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
16da0 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
16db0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
16dc0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
16dd0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
16de0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
16df0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
16e00 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
16e10 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
16e20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16e30 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
16e40 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
16e50 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
16e60 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
16e70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
16e80 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
16e90 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
16ea0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
16eb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
16ec0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
16ed0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
16ee0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
16ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
16f00 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
16f10 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
16f20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
16f30 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
16f40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
16f50 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
16f60 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
16f70 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
16f80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
16f90 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
16fa0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
16fb0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
16fc0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
16fd0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
16fe0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
16ff0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17000 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
17010 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
17020 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
17030 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
17040 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
17050 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
17060 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
17070 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
17080 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
17090 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
170a0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
170b0 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
170c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
170d0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
170e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
170f0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
17100 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
17110 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
17120 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
17130 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
17140 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
17150 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
17160 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
17170 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
17180 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17190 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
171a0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
171b0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
171c0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
171d0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
171e0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
171f0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
17200 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
17210 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
17220 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
17230 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
17240 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17250 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
17260 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
17270 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
17280 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
17290 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
172a0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
172b0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
172c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
172d0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
172e0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
172f0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
17300 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
17310 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
17320 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
17330 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
17340 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
17350 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17360 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
17370 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
17380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
17390 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
173a0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
173b0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
173c0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
173d0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
173e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
173f0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
17400 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
17410 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
17420 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
17430 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
17440 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
17450 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
17460 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
17470 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
17480 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
17490 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
174a0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
174b0 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
174c0 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
174d0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
174e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
174f0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
17500 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
17510 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
17520 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
17530 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
17540 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
17550 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
17560 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
17570 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
17580 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
17590 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
175a0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
175b0 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
175c0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
175d0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
175e0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
175f0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
17600 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
17610 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
17620 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
17630 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
17640 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
17650 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
17660 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
17670 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
17680 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
17690 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
176a0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
176b0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
176c0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
176d0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
176e0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
176f0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
17700 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
17710 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
17720 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
17730 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
17740 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
17750 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
17760 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
17770 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
17780 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
17790 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
177a0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
177b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
177c0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
177d0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
177e0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
177f0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
17800 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
17810 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
17820 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
17830 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
17840 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
17850 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
17860 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
17870 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
17880 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
17890 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
178a0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
178b0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
178c0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
178d0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
178e0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
178f0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
17900 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
17910 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
17920 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
17930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17940 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
17950 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
17960 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17970 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
17980 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
17990 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
179a0 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
179b0 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
179c0 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
179d0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
179e0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
179f0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
17a00 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
17a10 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
17a20 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
17a30 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
17a40 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
17a50 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
17a60 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
17a70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
17a80 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
17a90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17aa0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
17ab0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
17ac0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
17ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17ae0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
17af0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
17b00 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
17b10 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
17b20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17b30 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
17b40 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
17b50 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
17b60 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
17b70 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
17b80 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
17b90 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
17ba0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
17bb0 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
17bc0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
17bd0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
17be0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
17bf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
17c00 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
17c10 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
17c20 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
17c30 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
17c40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17c50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
17c60 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
17c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
17c80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
17c90 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
17ca0 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
17cb0 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
17cc0 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
17cd0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
17ce0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
17cf0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
17d00 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
17d10 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
17d20 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
17d30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17d40 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
17d50 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
17d60 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
17d70 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
17d80 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17d90 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
17da0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
17db0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
17dc0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17dd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17de0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
17df0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
17e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17e10 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
17e20 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
17e30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17e40 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
17e50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17e60 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
17e70 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
17e80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
17e90 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
17ea0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
17eb0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
17ec0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
17ed0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
17ee0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
17ef0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
17f00 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17f10 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
17f20 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
17f30 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
17f40 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
17f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17f60 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
17f70 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
17f80 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
17f90 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
17fa0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
17fb0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
17fc0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
17fd0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
17fe0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
17ff0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
18000 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
18010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
18020 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18030 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
18040 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
18050 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
18060 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
18070 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
18080 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
18090 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
180a0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
180b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
180c0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
180d0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
180e0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
180f0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
18100 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
18110 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
18120 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
18130 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
18140 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18150 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
18160 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
18170 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
18180 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
18190 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
181a0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
181b0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
181c0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
181d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
181e0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
181f0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
18200 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
18210 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
18220 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
18230 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
18240 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18250 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
18260 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
18270 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
18280 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18290 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
182a0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
182b0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
182c0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
182d0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
182e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
182f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18300 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
18310 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
18320 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
18330 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
18340 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
18350 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18360 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18370 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18380 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18390 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
183a0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
183b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
183c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
183d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
183e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
183f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
18400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18410 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
18420 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
18430 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18440 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18450 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18460 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
18470 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
18480 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
184a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
184b0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
184c0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
184d0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
184e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
184f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18500 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
18510 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18540 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18550 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
18560 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18570 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18590 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
185a0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
185b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
185c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
185d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
185e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
185f0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
18600 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18610 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18630 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
18640 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
18650 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18660 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18680 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
18690 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
186a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
186b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
186c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
186d0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
186e0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
186f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18720 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
18730 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
18740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18750 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18770 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
18780 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
18790 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
187a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
187b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187c0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
187d0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
187e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
187f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18810 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
18820 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
18830 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18840 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18860 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
18870 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
18880 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
188a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
188b0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
188c0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
188d0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
188e0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
188f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18900 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
18910 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
18920 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18930 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18940 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
18950 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18960 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
18970 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18980 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18990 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
189a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
189b0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
189c0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
189d0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
189e0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
189f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
18a00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18a10 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
18a20 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18a30 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
18a40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
18a50 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
18a60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18a70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18a80 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
18a90 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
18aa0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
18ab0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18ac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18ad0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
18ae0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
18af0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18b00 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
18b10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18b20 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
18b30 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
18b40 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
18b50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18b60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18b70 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
18b80 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
18b90 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
18ba0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18bc0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
18bd0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
18be0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
18bf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c10 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
18c20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
18c30 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
18c40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c60 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
18c70 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
18c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18c90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18cb0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
18cc0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
18cd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
18ce0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
18cf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18d00 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
18d10 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
18d20 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
18d30 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
18d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
18d50 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
18d60 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
18d70 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
18d80 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
18d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
18da0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
18db0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
18dc0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
18dd0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
18de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
18df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18e00 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
18e10 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
18e20 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
18e30 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
18e40 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
18e50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18e60 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
18e70 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
18e80 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
18e90 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
18ea0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
18eb0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
18ec0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
18ed0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
18ee0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
18ef0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
18f00 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
18f10 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
18f20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
18f30 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
18f40 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
18f50 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
18f60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
18f70 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
18f80 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
18f90 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
18fa0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
18fb0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
18fc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
18fd0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
18fe0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
18ff0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
19000 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
19010 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
19020 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
19030 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
19040 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
19050 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
19060 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
19070 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
19080 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
19090 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
190a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
190b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
190c0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
190d0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
190e0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
190f0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
19100 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
19110 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
19120 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
19130 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
19140 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
19150 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
19160 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
19170 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
19180 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
19190 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f  ok to run..*/.vo
191a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
191b0 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
191c0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
191d0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
191e0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
191f0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
19200 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19210 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
19220 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
19230 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
19240 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
19250 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19260 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
19270 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
19280 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
19290 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
192a0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
192b0 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
192c0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
192d0 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
192e0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
192f0 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
19300 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
19310 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
19320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19330 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
19340 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
19350 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
19360 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
19370 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
19380 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
19390 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
193a0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ery..**.** ^If t
193b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
193c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
193d0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
193e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
193f0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
19400 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
19410 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
19420 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
19430 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
19440 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
19450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
19460 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73  ress handler mus
19470 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
19480 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
19490 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
194a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
194b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
194c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
194d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
194e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
194f0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
19500 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
19510 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
19520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19530 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
19540 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
19550 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
19560 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
19570 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19580 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19590 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
195a0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
195b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
195c0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
195d0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
195e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
195f0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
19600 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
19610 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
19620 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
19630 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
19640 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
19650 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
19660 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
19670 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
19680 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19690 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
196a0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
196b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
196c0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
196d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
196e0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
196f0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
19700 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
19710 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
19720 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
19730 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
19740 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
19750 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
19760 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
19770 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
19780 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
19790 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
197a0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
197b0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
197c0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
197d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
197e0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
197f0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
19800 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
19810 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
19820 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
19830 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
19840 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
19850 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
19860 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
19870 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
19880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
19890 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
198a0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
198b0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
198c0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
198d0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
198e0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
198f0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
19900 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
19910 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
19920 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
19930 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
19940 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
19950 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
19960 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
19970 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
19980 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
19990 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
199a0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
199b0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
199c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
199d0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
199e0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
199f0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
19a00 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
19a10 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
19a20 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
19a30 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
19a40 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
19a50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
19a60 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
19a70 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
19a80 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
19a90 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
19aa0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
19ab0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
19ac0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
19ad0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
19ae0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
19af0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
19b00 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
19b10 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
19b20 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
19b30 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
19b40 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
19b50 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
19b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
19b70 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
19b80 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
19b90 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
19ba0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
19bb0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
19bc0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
19bd0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
19be0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
19bf0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
19c00 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
19c10 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
19c20 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
19c30 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
19c40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
19c50 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
19c60 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
19c70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
19c80 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
19c90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
19ca0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
19cb0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
19cc0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
19cd0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
19ce0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
19cf0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
19d00 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
19d10 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
19d20 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19d30 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
19d40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
19d50 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
19d60 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
19d70 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
19d80 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
19d90 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
19da0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
19db0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
19dc0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
19dd0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
19de0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
19df0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
19e00 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
19e10 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
19e20 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
19e30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
19e40 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
19e50 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
19e60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
19e70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
19e80 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
19e90 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
19ea0 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
19eb0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
19ec0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
19ed0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
19ee0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
19ef0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
19f00 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
19f10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
19f20 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
19f30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
19f40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
19f50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
19f60 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
19f70 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
19f80 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
19f90 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
19fa0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
19fb0 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
19fc0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
19fd0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
19fe0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
19ff0 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51  LLMUTEX],.** [SQ
1a000 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1a010 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53  CACHE] and/or [S
1a020 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1a030 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  DCACHE] flags,.*
1a040 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1a050 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1a060 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a070 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a080 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1a090 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1a0a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a0b0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1a0c0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1a0d0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1a0e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1a0f0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1a100 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1a110 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1a120 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1a130 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1a140 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1a150 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1a160 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1a170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a180 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1a190 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1a1a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1a1b0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1a1c0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1a1d0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1a1e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1a1f0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1a200 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1a210 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1a220 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1a230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a240 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1a250 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1a260 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1a270 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1a280 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1a290 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1a2a0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1a2b0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1a2c0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1a2d0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1a2e0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1a2f0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1a300 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a310 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1a320 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1a330 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1a340 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1a350 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1a360 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1a370 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1a380 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1a390 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1a3a0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1a3b0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1a3c0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1a3d0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1a3e0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1a3f0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1a400 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a410 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1a420 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1a430 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1a440 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1a450 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1a460 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1a470 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1a480 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1a490 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1a4a0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1a4b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1a4c0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1a4d0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1a4e0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1a4f0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1a500 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1a510 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1a520 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1a530 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1a540 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a550 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1a560 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1a570 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1a580 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1a590 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1a5a0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1a5b0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1a5c0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1a5d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1a5e0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1a5f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a600 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1a610 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1a620 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1a630 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1a640 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1a650 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1a660 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1a670 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1a680 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1a690 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1a6a0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1a6b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1a6c0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1a6d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1a6e0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1a6f0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1a700 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1a710 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1a720 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1a730 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1a740 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1a750 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1a760 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1a770 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1a780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1a790 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1a7a0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1a7b0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1a7c0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1a7d0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1a7e0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1a7f0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1a800 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1a810 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1a820 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1a830 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1a840 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1a850 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1a860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a870 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1a880 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1a890 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a8a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a8b0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a8c0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a8d0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1a8e0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a8f0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a900 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1a910 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1a920 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1a930 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1a940 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1a950 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1a960 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a970 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a980 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1a990 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1a9a0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a9b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a9c0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a9d0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a9e0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1a9f0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1aa00 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1aa10 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1aa20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1aa30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1aa40 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1aa50 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1aa60 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1aa70 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1aa80 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1aa90 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1aaa0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1aab0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1aac0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1aad0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1aae0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1aaf0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1ab00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1ab10 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1ab20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1ab30 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1ab40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab50 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1ab60 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1ab70 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1ab80 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1ab90 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1aba0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1abb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1abc0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1abd0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1abe0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1abf0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1ac00 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1ac10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1ac20 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1ac30 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1ac40 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1ac50 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1ac60 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1ac70 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1ac80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1ac90 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1aca0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1acb0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1acc0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1acd0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ace0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1acf0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ad00 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1ad10 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1ad20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1ad30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1ad40 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1ad50 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1ad60 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1ad70 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1ad80 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1ad90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1ada0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1adb0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1adc0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1add0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1ade0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1adf0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1ae00 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1ae10 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1ae20 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1ae30 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1ae40 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1ae50 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1ae60 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1ae70 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1ae80 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1ae90 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1aea0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1aeb0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1aec0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1aed0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1aee0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1aef0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1af00 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1af10 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1af20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1af30 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1af40 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1af50 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1af60 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1af70 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1af80 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1af90 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1afa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1afb0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1afc0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1afd0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1afe0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1aff0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1b000 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1b010 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1b020 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1b030 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1b040 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1b050 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1b060 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1b070 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1b080 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1b090 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1b0a0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1b0b0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1b0c0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1b0d0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1b0e0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1b0f0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1b100 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1b110 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1b120 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1b130 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1b140 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1b150 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b160 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1b170 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1b180 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1b190 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1b1a0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1b1b0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1b1c0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1b1d0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1b1e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1b1f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1b200 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1b210 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1b220 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1b230 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1b240 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1b250 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1b260 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1b270 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1b280 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1b290 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1b2a0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1b2b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1b2c0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1b2d0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1b2e0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1b2f0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1b300 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1b310 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1b320 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1b330 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1b340 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1b350 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1b360 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1b370 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1b380 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1b390 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1b3a0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1b3b0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1b3c0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1b3d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1b3e0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1b3f0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1b400 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1b410 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b420 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1b430 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1b440 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1b450 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1b460 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1b470 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1b480 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1b490 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1b4a0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1b4b0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1b4c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b4d0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1b4e0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1b4f0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1b500 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1b510 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1b520 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b530 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1b540 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1b550 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1b560 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1b570 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1b580 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1b590 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1b5a0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1b5b0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1b5c0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1b5d0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1b5e0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1b5f0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1b600 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b610 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1b620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b630 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1b640 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1b650 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1b660 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b670 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1b680 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1b690 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1b6a0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1b6b0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1b6c0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1b6d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1b6e0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1b6f0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1b700 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1b710 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b720 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a  e old limit.)^.*
1b730 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1b740 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1b750 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1b760 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1b770 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68  ged..** ^(For th
1b780 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1b790 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1b7a0 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1b7b0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1b7c0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1b7d0 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  ** set by a comp
1b7e0 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
1b7f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
1b800 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  med .** [limits 
1b810 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  | SQLITE_MAX_XYZ
1b820 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1b830 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1b840 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1b850 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1b860 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1b870 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1b880 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1b890 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1b8a0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1b8b0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1b8c0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1b8d0 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
1b8e0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1b8f0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1b900 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1b910 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1b920 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1b930 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1b940 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1b950 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1b960 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1b970 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1b980 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1b990 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1b9a0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
1b9b0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1b9c0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1b9d0 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1b9e0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1b9f0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1ba00 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1ba10 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1ba20 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1ba30 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1ba40 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1ba50 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1ba60 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1ba70 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1ba80 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1ba90 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1baa0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1bab0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1bac0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1bad0 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1bae0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1baf0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1bb00 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1bb10 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1bb20 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1bb30 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1bb40 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1bb50 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1bb60 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1bb70 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1bb80 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1bb90 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1bba0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1bbb0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1bbc0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1bbd0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1bbe0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1bbf0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1bc00 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1bc10 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1bc20 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1bc30 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1bc40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1bc50 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1bc60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bc70 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1bc80 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1bc90 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1bca0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1bcb0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1bcc0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1bcd0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1bce0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1bcf0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1bd00 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1bd10 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1bd20 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1bd30 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1bd40 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1bd50 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1bd60 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1bd70 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1bd80 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1bd90 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1bda0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1bdb0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1bdc0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1bdd0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1bde0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1bdf0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1be00 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1be10 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1be20 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a   row.<dd>)^.**.*
1be30 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1be40 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1be50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1be60 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1be70 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1be80 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
1be90 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1bea0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1beb0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1bec0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1bed0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1bee0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1bef0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1bf00 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1bf10 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
1bf20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1bf30 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1bf40 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1bf50 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1bf60 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1bf70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1bf80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1bf90 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1bfa0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1bfb0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1bfc0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1bfd0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1bfe0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1bff0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1c000 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1c010 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c020 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c030 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1c040 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1c050 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1c060 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c070 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1c080 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c090 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c0a0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1c0b0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1c0c0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1c0d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1c0e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c0f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c100 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c110 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1c120 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c130 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c140 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1c150 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
1c160 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c170 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1c180 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1c190 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c1a0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1c1b0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1c1c0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
1c1d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c1e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1c1f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1c200 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c210 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1c220 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1c230 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
1c240 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
1c250 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
1c260 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c270 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c280 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1c290 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c2a0 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1c2b0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c2c0 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1c2d0 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29   be bound.</dd>)
1c2e0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c2f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1c300 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1c310 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c320 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1c330 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1c340 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1c350 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1c360 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1c370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c380 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1c390 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1c3a0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1c3b0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1c3c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1c3d0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1c3e0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1c3f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1c400 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1c410 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1c420 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1c430 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1c440 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1c450 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1c460 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1c470 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1c480 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c490 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1c4a0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1c4b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c4c0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1c4d0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1c4e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c4f0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1c500 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1c510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c520 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c530 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1c540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c550 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1c560 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1c570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c580 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1c590 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1c5a0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1c5b0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1c5c0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1c5d0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1c5e0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1c5f0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1c600 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1c610 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1c620 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1c630 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1c640 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1c650 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1c660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1c670 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1c680 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1c690 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1c6a0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1c6b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1c6c0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1c6d0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1c6e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c6f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1c700 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1c710 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1c720 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1c730 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1c740 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1c750 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1c760 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1c770 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1c780 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1c790 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1c7a0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1c7b0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1c7c0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1c7d0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1c7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1c7f0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1c800 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1c810 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1c820 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1c830 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1c840 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1c850 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1c860 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1c870 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1c880 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1c890 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1c8a0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1c8b0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1c8c0 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1c8d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1c8e0 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1c8f0 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1c900 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1c910 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1c920 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1c930 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1c940 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1c950 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1c960 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1c970 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1c980 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1c990 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1c9a0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1c9b0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1c9c0 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1c9d0 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1c9e0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1c9f0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1ca00 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1ca10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1ca20 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1ca30 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1ca40 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1ca50 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1ca60 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1ca70 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1ca80 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1ca90 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1caa0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1cab0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1cac0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1cad0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1cae0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1caf0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1cb00 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1cb10 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1cb20 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1cb30 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1cb40 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1cb50 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1cb60 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1cb70 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1cb80 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1cb90 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1cba0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1cbb0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1cbc0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1cbd0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1cbe0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1cbf0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1cc00 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1cc10 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1cc20 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1cc30 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1cc40 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1cc50 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1cc60 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1cc70 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1cc80 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1cc90 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1cca0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1ccb0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1ccc0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1ccd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1cce0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1ccf0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1cd00 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1cd10 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1cd20 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1cd30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1cd40 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1cd50 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1cd60 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1cd70 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1cd80 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1cd90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1cda0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cdb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cdc0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1cdd0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1cde0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1cdf0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1ce00 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1ce10 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1ce20 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1ce30 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1ce40 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1ce50 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1ce60 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1ce70 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1ce80 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1ce90 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1cea0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1ceb0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1cec0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1ced0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1cee0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1cef0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1cf00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1cf10 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1cf20 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1cf30 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1cf40 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1cf50 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1cf60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1cf70 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1cf80 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1cf90 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1cfa0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1cfb0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1cfc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1cfd0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1cfe0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1cff0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1d000 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1d010 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20   it again.  ^If 
1d020 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1d030 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1d040 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1d050 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1d060 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1d070 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d080 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1d090 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1d0a0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1d0b0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1d0c0 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1d0d0 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1d0e0 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1d0f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1d100 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1d110 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1d120 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1d130 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1d140 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1d150 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1d160 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1d170 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1d180 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1d190 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1d1a0 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1d1b0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1d1c0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1d1d0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1d1e0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1d1f0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1d200 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1d210 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1d220 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1d230 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1d240 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1d250 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1d260 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1d270 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1d280 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1d290 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1d2a0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1d2b0 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1d2c0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1d2d0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1d2e0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1d2f0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1d300 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1d310 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1d320 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1d330 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1d340 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1d350 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1d360 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1d370 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1d380 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1d390 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1d3a0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  f the value of a
1d3b0 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
1d3c0 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
1d3d0 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
1d3e0 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67  e might.** chang
1d3f0 65 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  e the query plan
1d400 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1d410 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  , then the state
1d420 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61  ment may be.** a
1d430 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1d440 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20 74  ompiled (as if t
1d450 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 20  here had been a 
1d460 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f  schema change) o
1d470 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20  n the first .** 
1d480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d490 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
1d4a0 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68  any change to th
1d4b0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  e .** [sqlite3_b
1d4c0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
1d4d0 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72  ngs] of the [par
1d4e0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c  ameter]. .** </l
1d4f0 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1d500 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1d510 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1d520 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1d530 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1d540 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1d550 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1d560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1d570 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1d580 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1d590 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1d5a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1d5b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1d5c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1d5d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1d5e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1d5f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d600 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1d610 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1d620 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1d630 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1d640 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1d650 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1d660 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d670 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1d680 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d690 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1d6a0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1d6b0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1d6c0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1d6d0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1d6e0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1d6f0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1d700 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1d710 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1d720 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1d730 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1d740 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1d750 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1d760 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1d770 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1d780 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1d790 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1d7a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d7b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1d7c0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1d7d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1d7e0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1d7f0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1d800 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1d810 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1d820 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1d830 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1d840 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1d850 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1d860 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1d870 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1d880 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1d890 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1d8a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1d8b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1d8c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1d8d0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1d8e0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1d8f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d900 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1d910 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d920 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1d930 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1d940 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1d950 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1d960 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1d970 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1d980 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1d990 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1d9a0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1d9b0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1d9c0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1d9d0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1d9e0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1d9f0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1da00 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1da10 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1da20 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1da30 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1da40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1da50 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1da60 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1da70 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1da80 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1da90 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1daa0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1dab0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1dac0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1dad0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1dae0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1daf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1db00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1db10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1db20 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1db30 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1db40 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1db50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1db60 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1db70 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1db80 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1db90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1dba0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1dbb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1dbc0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1dbd0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1dbe0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1dbf0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1dc00 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1dc10 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1dc20 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1dc30 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1dc40 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1dc50 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1dc60 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
1dc70 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1dc80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1dc90 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1dca0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1dcb0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1dcc0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1dcd0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1dce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1dcf0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1dd00 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1dd10 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1dd20 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1dd30 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1dd40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1dd50 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1dd60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1dd70 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1dd80 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1dd90 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1dda0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1ddb0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1ddc0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1ddd0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1dde0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1ddf0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1de00 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1de10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1de20 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1de30 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1de40 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1de50 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1de60 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1de70 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1de80 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1de90 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1dea0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1deb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1dec0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1ded0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1dee0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1def0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1df00 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1df10 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1df20 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1df30 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1df40 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1df50 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1df60 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1df70 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1df80 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1df90 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1dfa0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1dfb0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1dfc0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1dfd0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1dfe0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1dff0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1e000 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1e010 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1e020 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1e030 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1e040 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1e050 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1e060 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1e070 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1e080 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1e090 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1e0a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e0b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1e0c0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1e0d0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1e0e0 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1e0f0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1e100 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e110 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e120 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1e130 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1e140 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1e150 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e160 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1e170 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1e180 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1e190 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1e1a0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1e1b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1e1c0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1e1d0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
1e1e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e1f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1e200 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e210 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1e220 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1e230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e240 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1e250 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1e260 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1e270 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1e280 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1e290 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1e2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1e2b0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1e2c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1e2d0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1e2e0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1e2f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e300 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1e310 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1e320 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1e330 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1e340 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1e350 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1e360 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
1e370 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1e380 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1e390 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1e3a0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1e3b0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1e3c0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
1e3d0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1e3e0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1e3f0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1e400 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1e410 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1e420 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1e430 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1e440 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1e450 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1e460 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1e470 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1e480 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1e490 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1e4a0 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1e4b0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1e4c0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1e4d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1e4e0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1e4f0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1e500 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1e510 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1e520 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1e530 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1e540 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1e550 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1e560 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1e570 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1e580 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1e590 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1e5a0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1e5b0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
1e5c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
1e5d0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
1e5e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
1e5f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
1e600 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
1e610 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
1e620 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
1e630 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
1e640 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
1e650 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
1e660 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
1e670 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1e680 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
1e690 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
1e6a0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
1e6b0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
1e6c0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
1e6d0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
1e6e0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
1e6f0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
1e700 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
1e710 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
1e720 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
1e730 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
1e740 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
1e750 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
1e760 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
1e770 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
1e780 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
1e790 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
1e7a0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
1e7b0 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20  ic identifer.)^ 
1e7c0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
1e7d0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1e7e0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1e7f0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1e800 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1e810 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1e820 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1e830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1e840 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1e850 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1e860 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1e870 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1e880 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1e890 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1e8a0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1e8b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1e8c0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1e8d0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1e8e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e8f0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e900 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1e910 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1e920 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
1e930 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1e940 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
1e950 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
1e960 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
1e970 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
1e980 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
1e990 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
1e9a0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
1e9b0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
1e9c0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
1e9d0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
1e9e0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
1e9f0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
1ea00 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
1ea10 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
1ea20 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1ea30 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1ea40 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1ea50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ea60 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1ea70 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1ea80 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
1ea90 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1eaa0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1eab0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
1eac0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1ead0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1eae0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1eaf0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1eb00 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1eb10 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1eb20 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1eb30 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1eb40 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
1eb50 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
1eb60 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
1eb70 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
1eb80 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
1eb90 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1eba0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1ebb0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1ebc0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1ebd0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
1ebe0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1ebf0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1ec00 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1ec10 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
1ec20 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
1ec30 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1ec40 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
1ec50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
1ec60 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1ec70 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1ec80 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1ec90 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1eca0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1ecb0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1ecc0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1ecd0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
1ece0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1ecf0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1ed00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1ed10 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1ed20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1ed30 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1ed40 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1ed50 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1ed60 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1ed70 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1ed80 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49  shed with it. ^I
1ed90 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1eda0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1edb0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1edc0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1edd0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1ede0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1edf0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1ee00 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1ee10 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1ee20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1ee30 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
1ee40 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1ee50 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1ee60 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1ee70 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1ee80 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1ee90 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1eea0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1eeb0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1eec0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1eed0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1eee0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
1eef0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1ef00 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1ef10 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1ef20 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1ef30 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1ef40 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
1ef50 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1ef60 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1ef70 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1ef80 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1ef90 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
1efa0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1efb0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1efc0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1efd0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1efe0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
1eff0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
1f000 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
1f010 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
1f020 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1f030 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
1f040 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1f050 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
1f060 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
1f070 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
1f080 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
1f090 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
1f0a0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
1f0b0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f0c0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1f0d0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1f0e0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
1f0f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f100 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
1f110 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f120 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
1f130 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f140 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1f150 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
1f160 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
1f170 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
1f180 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
1f190 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
1f1a0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
1f1b0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
1f1c0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
1f1d0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
1f1e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
1f1f0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
1f200 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
1f210 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f220 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
1f230 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
1f240 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1f250 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1f260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1f270 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
1f280 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
1f290 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f2a0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1f2b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
1f2c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f2d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
1f2e0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
1f2f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
1f300 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
1f310 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
1f320 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
1f330 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
1f340 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
1f350 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
1f360 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
1f370 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
1f380 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
1f390 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f3a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f3b0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1f3c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1f3d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1f3e0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1f3f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f400 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
1f410 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1f420 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1f430 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1f440 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1f450 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1f460 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1f470 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1f480 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1f490 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f4a0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1f4b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1f4c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f4d0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1f4e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1f4f0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1f500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1f510 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1f520 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1f530 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1f540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f550 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1f560 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1f570 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1f580 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1f590 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f5a0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1f5b0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1f5c0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1f5d0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1f5e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f5f0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1f600 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1f610 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1f620 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f630 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1f640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f650 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1f660 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
1f670 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
1f680 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
1f690 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
1f6a0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
1f6b0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
1f6c0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
1f6d0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1f6e0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
1f6f0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
1f700 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
1f710 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
1f720 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
1f730 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
1f740 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
1f750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f760 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
1f770 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
1f780 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
1f790 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
1f7a0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
1f7b0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
1f7c0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
1f7d0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
1f7e0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
1f7f0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
1f800 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
1f810 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
1f820 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
1f830 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
1f840 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
1f850 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
1f860 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
1f870 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
1f880 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
1f890 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f8a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f8b0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1f8c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f8d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f8e0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1f8f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f900 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1f910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1f920 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1f930 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1f940 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f950 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
1f960 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
1f970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f980 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f990 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
1f9a0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
1f9b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
1f9c0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
1f9d0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
1f9e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f9f0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
1fa00 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
1fa10 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
1fa20 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1fa30 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
1fa40 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
1fa50 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
1fa60 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1fa70 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1fa80 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
1fa90 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
1faa0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
1fab0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
1fac0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
1fad0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
1fae0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
1faf0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
1fb00 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1fb10 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1fb20 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1fb30 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1fb40 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
1fb50 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
1fb60 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
1fb70 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
1fb80 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
1fb90 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1fba0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
1fbb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
1fbc0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
1fbd0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
1fbe0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
1fbf0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
1fc00 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
1fc10 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
1fc20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
1fc30 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
1fc40 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
1fc50 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
1fc60 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
1fc70 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
1fc80 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
1fc90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fca0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
1fcb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1fcc0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
1fcd0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1fce0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1fcf0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1fd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fd10 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
1fd20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1fd30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1fd40 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
1fd50 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1fd60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1fd70 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fd80 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
1fd90 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
1fda0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
1fdb0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
1fdc0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
1fdd0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1fde0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
1fdf0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
1fe00 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
1fe10 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
1fe20 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
1fe30 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
1fe40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1fe50 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1fe60 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
1fe70 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
1fe80 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1fe90 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1fea0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
1feb0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1fec0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1fed0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1fee0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1fef0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1ff00 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1ff10 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1ff20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ff30 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1ff40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1ff50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1ff60 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1ff70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ff80 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1ff90 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1ffa0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1ffb0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
1ffc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ffd0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ffe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
20000 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
20010 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
20020 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
20030 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
20040 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
20050 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
20060 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
20070 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
20080 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
20090 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
200a0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
200b0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
200c0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
200d0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
200e0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
200f0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
20100 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
20110 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
20120 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
20130 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
20140 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
20150 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
20160 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
20170 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
20180 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
20190 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
201a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
201b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
201c0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
201d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
201e0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
201f0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
20200 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
20210 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
20220 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
20230 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ])..*/.int sqlit
20240 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
20250 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
20260 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
20270 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
20280 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
20290 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
202a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
202b0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
202c0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
202d0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
202e0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
202f0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
20300 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
20310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20320 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
20330 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20340 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
20350 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
20360 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
20370 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
20380 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
20390 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
203a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
203b0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
203c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
203d0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
203e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
203f0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
20400 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
20410 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
20420 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20430 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
20440 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
20450 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
20460 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
20470 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
20480 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
20490 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
204a0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
204b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
204c0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
204d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
204e0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
204f0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
20500 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
20510 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
20520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
20530 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
20540 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
20550 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20560 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
20570 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
20580 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
20590 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
205a0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
205b0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
205c0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
205d0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
205e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
205f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
20600 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
20610 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
20620 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
20630 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
20640 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
20650 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
20660 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
20670 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
20680 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
20690 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
206a0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
206b0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
206c0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
206d0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
206e0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
206f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20700 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20710 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
20720 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
20730 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
20740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20750 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
20760 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
20770 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
20780 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
20790 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
207a0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
207b0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
207c0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
207d0 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
207e0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
207f0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
20800 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
20810 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
20820 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
20830 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
20840 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
20850 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
20860 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
20870 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
20880 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
20890 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
208a0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
208b0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
208c0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
208d0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
208e0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
208f0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
20900 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
20910 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
20920 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
20930 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
20940 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
20950 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
20960 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
20970 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
20980 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
20990 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
209a0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
209b0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
209c0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
209d0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
209e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
209f0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
20a00 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
20a10 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
20a20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
20a30 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
20a40 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
20a50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
20a60 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
20a70 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
20a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
20a90 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
20aa0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
20ab0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
20ac0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
20ad0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
20ae0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
20af0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
20b00 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
20b10 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20b20 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
20b30 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
20b40 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
20b50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
20b60 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
20b70 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
20b80 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
20b90 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
20ba0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
20bb0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
20bc0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
20bd0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
20be0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
20bf0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
20c00 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
20c10 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
20c20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
20c30 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
20c40 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
20c50 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
20c60 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
20c70 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
20c80 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
20c90 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
20ca0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
20cb0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
20cc0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
20cd0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
20ce0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
20cf0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
20d00 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
20d10 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
20d20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
20d30 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
20d40 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
20d50 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
20d60 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
20d70 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
20d80 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
20d90 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
20da0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
20db0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
20dc0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
20dd0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
20de0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
20df0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
20e00 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
20e10 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
20e20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20e30 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
20e40 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
20e50 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
20e60 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
20e70 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
20e80 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
20e90 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
20ea0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20eb0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
20ec0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
20ed0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
20ee0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
20ef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20f00 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
20f10 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
20f20 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
20f30 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
20f40 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
20f50 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
20f60 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
20f70 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
20f80 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
20f90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
20fa0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
20fb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20fc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
20fd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
20fe0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
20ff0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
21000 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
21010 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
21020 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
21030 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21040 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21050 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
21060 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21070 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
21080 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21090 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
210a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
210b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
210c0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
210d0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
210e0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
210f0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
21100 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
21110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21120 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
21130 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
21140 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
21150 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
21160 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
21170 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
21180 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
21190 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
211a0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
211b0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
211c0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
211d0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
211e0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
211f0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
21200 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
21210 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
21220 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
21230 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
21240 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
21250 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
21260 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
21270 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21280 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
21290 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
212a0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
212b0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
212c0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
212d0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
212e0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
212f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
21300 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
21310 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
21320 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
21330 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
21340 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
21350 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
21360 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
21370 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
21380 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
21390 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
213a0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
213b0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
213c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
213d0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
213e0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
213f0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
21400 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
21410 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
21420 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
21430 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
21440 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
21450 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
21460 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
21470 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
21480 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
21490 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
214a0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
214b0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
214c0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
214d0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
214e0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
214f0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
21500 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
21510 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
21520 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
21530 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
21540 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
21550 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21560 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
21570 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21580 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21590 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
215a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
215b0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
215c0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
215d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
215e0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
215f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21600 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
21610 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
21620 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
21630 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21650 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
21660 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
21670 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
21680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
21690 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
216a0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
216b0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
216c0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
216d0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
216e0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
216f0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
21700 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
21710 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
21720 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21730 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
21740 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
21750 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
21760 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
21770 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
21780 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
21790 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
217a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
217b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
217c0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
217d0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
217e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
217f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
21800 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
21810 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
21820 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
21830 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
21840 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
21850 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
21860 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
21870 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
21880 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
21890 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
218a0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
218b0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
218c0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
218d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
218e0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
218f0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
21900 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
21910 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
21920 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
21930 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
21940 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
21950 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
21960 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
21970 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
21980 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
21990 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
219a0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
219b0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
219c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
219d0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
219e0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
219f0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
21a00 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
21a10 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
21a20 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
21a30 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
21a40 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
21a50 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
21a60 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
21a70 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
21a80 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
21a90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21aa0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
21ab0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
21ac0 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
21ad0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
21ae0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
21af0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
21b00 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
21b10 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
21b20 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
21b30 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
21b40 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
21b50 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
21b60 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
21b70 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
21b80 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
21b90 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
21ba0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
21bb0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
21bc0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
21bd0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21be0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
21bf0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
21c00 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
21c10 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
21c20 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
21c30 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
21c40 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
21c50 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
21c60 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
21c70 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
21c80 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
21c90 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
21ca0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
21cb0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
21cc0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
21cd0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
21ce0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
21cf0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
21d00 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
21d10 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
21d20 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
21d30 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
21d40 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
21d50 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
21d60 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
21d70 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
21d80 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
21d90 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
21da0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
21db0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
21dc0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
21dd0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
21de0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
21df0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
21e00 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
21e10 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
21e20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
21e30 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
21e40 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
21e50 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
21e60 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
21e70 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
21e80 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
21e90 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
21ea0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
21eb0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
21ec0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
21ed0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
21ee0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
21ef0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
21f00 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21f10 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
21f20 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
21f30 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
21f40 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
21f50 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
21f60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
21f70 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
21f80 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
21f90 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
21fa0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
21fb0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
21fc0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
21fd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
21fe0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
21ff0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
22000 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
22010 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
22020 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
22030 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
22040 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
22050 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
22060 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
22070 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
22080 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
22090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
220a0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
220b0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
220c0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
220d0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
220e0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
220f0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
22100 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
22110 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
22120 31 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72  1, it was requir
22130 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69  ed.** after sqli
22140 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
22150 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68  ned anything oth
22160 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22170 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71  ROW] that.** [sq
22180 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62  lite3_reset()] b
22190 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
221a0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
221b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
221c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
221d0 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f   Failure to invo
221e0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
221f0 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79  t()] in this way
22200 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74   would.** result
22210 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
22220 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
22230 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  om sqlite3_step(
22240 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a  ).  But after.**
22250 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
22260 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
22270 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20  ) began calling 
22280 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22290 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ] .** automatica
222a0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
222b0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20  umstance rather 
222c0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
222d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
222e0 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79   .**.** <b>Goofy
222f0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
22300 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
22310 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
22320 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
22330 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
22340 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
22350 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
22360 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
22370 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
22380 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
22390 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
223a0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
223b0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
223c0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
223d0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
223e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
223f0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
22400 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
22410 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
22420 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
22430 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
22440 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
22450 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
22460 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
22470 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
22480 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
22490 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
224a0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
224b0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
224c0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
224d0 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
224e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
224f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
22500 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22510 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
22520 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
22530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22540 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
22550 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
22560 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
22570 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
22580 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
22590 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
225a0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
225b0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
225c0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
225d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
225e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
225f0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
22600 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
22610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22620 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
22630 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
22640 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
22650 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
22660 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  P) the number of
22670 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
22680 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
22690 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
226a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
226b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
226c0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
226d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
226e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
226f0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
22700 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
22710 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
22720 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
22730 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
22740 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
22750 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
22760 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
22770 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
22780 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
22790 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
227a0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
227b0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
227c0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
227d0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
227e0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
227f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
22800 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
22810 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
22820 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
22830 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
22840 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
22850 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
22860 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
22870 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
22880 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
22890 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
228a0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
228b0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
228c0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
228d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
228e0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
228f0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
22900 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
22910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22920 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
22930 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
22940 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
22950 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
22960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
22970 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
22980 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
22990 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
229a0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
229b0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
229c0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
229d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
229e0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
229f0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
22a00 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
22a10 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
22a20 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
22a30 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
22a40 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
22a50 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
22a60 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
22a70 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
22a80 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
22a90 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
22aa0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
22ab0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
22ac0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
22ad0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
22ae0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
22af0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
22b00 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
22b10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22b20 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
22b30 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
22b40 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
22b50 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
22b60 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
22b70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22b80 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
22b90 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
22ba0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
22bb0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
22bc0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
22bd0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
22be0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
22bf0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
22c00 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
22c10 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
22c20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
22c30 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
22c40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22c50 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
22c60 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
22c70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
22c80 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
22c90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
22ca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
22cb0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
22cc0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
22cd0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
22ce0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
22cf0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
22d00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
22d10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
22d20 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
22d30 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
22d40 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
22d50 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
22d60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22d70 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
22d80 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
22d90 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
22da0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
22db0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22dc0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
22dd0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
22de0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
22df0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
22e00 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
22e10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22e20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
22e30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22e40 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
22e50 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
22e60 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
22e70 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
22e80 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
22e90 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
22ea0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
22eb0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
22ec0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22ed0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
22ee0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
22ef0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
22f00 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
22f10 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
22f20 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
22f30 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
22f40 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
22f50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
22f60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
22f70 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
22f80 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
22f90 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
22fa0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
22fb0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
22fc0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
22fd0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
22fe0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
22ff0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
23000 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
23010 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
23020 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
23030 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
23040 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
23050 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
23060 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
23070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23080 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
23090 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
230a0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
230b0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
230c0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
230d0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
230e0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
230f0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
23100 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
23110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23120 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
23130 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
23140 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23150 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
23160 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
23170 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
23180 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
23190 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
231a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
231b0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
231c0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
231d0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
231e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
231f0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
23200 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
23210 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
23220 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
23230 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
23240 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
23250 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
23260 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23270 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
23280 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
23290 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
232a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
232b0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
232c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
232d0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
232e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
232f0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
23300 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
23310 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
23320 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
23330 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
23340 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
23350 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
23360 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
23370 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
23380 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
23390 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
233a0 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
233b0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
233c0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
233d0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
233e0 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
233f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
23400 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
23410 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
23420 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
23430 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
23440 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
23450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23460 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
23470 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
23480 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
23490 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
234a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
234b0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
234c0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
234d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
234e0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
234f0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
23500 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
23510 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
23520 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
23530 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
23540 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23550 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
23560 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
23570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23580 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
23590 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
235a0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
235b0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
235c0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
235d0 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  * ^The zero term
235e0 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
235f0 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
23600 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ount..**.** ^The
23610 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23620 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
23630 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
23640 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
23650 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23660 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
23670 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23680 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
23690 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
236a0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
236b0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
236c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
236d0 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
236e0 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
236f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23700 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
23710 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
23720 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
23730 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
23740 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
23750 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
23760 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
23770 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
23780 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
23790 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
237a0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
237b0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
237c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
237d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
237e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
237f0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
23800 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
23810 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
23820 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
23830 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
23840 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
23850 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
23860 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
23870 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
23880 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
23890 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
238a0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
238b0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
238c0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
238d0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
238e0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
238f0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
23900 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
23910 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
23920 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
23930 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
23940 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
23950 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
23960 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
23970 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
23980 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
23990 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
239a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
239b0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
239c0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
239d0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
239e0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
239f0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
23a00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23a10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
23a20 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23a30 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23a40 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23a50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
23a60 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23a70 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23a80 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
23a90 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
23aa0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
23ab0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
23ac0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
23ad0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23ae0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
23af0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
23b00 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
23b10 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
23b20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
23b30 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
23b40 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
23b50 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
23b60 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
23b70 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
23b80 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
23b90 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
23ba0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23bb0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
23bc0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
23bd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
23be0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
23bf0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
23c00 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
23c10 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23c20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
23c30 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
23c40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
23c50 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
23c60 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
23c70 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
23c80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
23c90 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
23ca0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
23cb0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
23cc0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23cd0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
23ce0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
23cf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
23d00 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
23d10 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
23d20 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
23d30 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
23d40 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
23d50 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23d60 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
23d70 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
23d80 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
23d90 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
23da0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
23db0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
23dc0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
23dd0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
23de0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
23df0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
23e00 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
23e10 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
23e20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
23e30 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
23e40 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
23e50 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
23e60 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
23e70 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
23e80 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
23e90 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
23ea0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
23eb0 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
23ec0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
23ed0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  mers..**.** ^Not
23ee0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
23ef0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
23f00 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
23f10 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
23f20 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
23f30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
23f40 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
23f50 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
23f60 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
23f70 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
23f80 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
23f90 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73  * ^(Type convers
23fa0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
23fb0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
23fc0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
23fd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23fe0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
23ff0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
24000 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
24010 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
24020 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
24030 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
24040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24050 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
24060 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
24070 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
24080 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
24090 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
240a0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
240b0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
240c0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
240d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
240e0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
240f0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
24100 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
24110 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
24120 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
24130 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
24140 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
24150 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
24160 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
24170 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
24180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24190 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
241a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
241b0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
241c0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
241d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
241e0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
241f0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
24200 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  >)^.**.** ^Conve
24210 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
24220 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
24230 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
24240 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
24250 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
24260 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
24270 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
24280 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
24290 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
242a0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
242b0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
242c0 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
242d0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
242e0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
242f0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
24300 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
24310 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
24320 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
24330 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
24340 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
24350 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
24360 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
24370 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
24380 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73  *.** ^(The safes
24390 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
243a0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
243b0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
243c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
243d0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
243e0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
243f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
24400 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
24410 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
24420 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24430 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
24440 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
24450 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
24460 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
24470 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
24480 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
24490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
244a0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
244b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
244c0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
244d0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
244e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
244f0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
24500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24510 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
24520 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
24530 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24540 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
24550 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
24560 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
24570 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
24580 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
24590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
245a0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
245b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
245c0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
245d0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
245e0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
245f0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
24600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
24610 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
24620 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
24630 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
24640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24650 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
24660 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
24670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24680 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
24690 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
246a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
246b0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
246c0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
246d0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
246e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
246f0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
24700 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
24710 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
24720 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
24730 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
24740 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24750 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
24760 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
24770 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
24780 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
24790 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
247a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
247b0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
247c0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
247d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
247e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
247f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
24800 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
24810 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
24820 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
24830 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
24840 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
24850 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
24860 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
24870 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
24880 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
24890 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
248a0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
248b0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
248c0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
248d0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
248e0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
248f0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
24900 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
24910 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
24920 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
24930 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
24940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
24950 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
24960 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24970 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
24980 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
249a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
249b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
249c0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
249d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
249e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
249f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
24a00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
24a10 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
24a20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24a40 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
24a50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24a60 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
24a70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24a80 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
24a90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24aa0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
24ab0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
24ac0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
24ad0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24ae0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24b00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
24b10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
24b20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
24b30 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
24b40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24b50 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
24b60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
24b70 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
24b80 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
24b90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24ba0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
24bb0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
24bc0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
24bd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24be0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
24bf0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
24c00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24c10 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
24c20 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
24c30 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
24c40 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
24c50 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
24c60 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
24c70 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66  is returned. ^If
24c80 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
24c90 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
24ca0 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65  ed then an.** [e
24cb0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
24cc0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
24cd0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
24ce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
24cf0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
24d00 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
24d10 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
24d20 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
24d30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24d40 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69  nt].  ^If the vi
24d50 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
24d60 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
24d70 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
24d80 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
24d90 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
24da0 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
24db0 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
24dc0 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
24dd0 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
24de0 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d  rupt]..** ^Incom
24df0 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
24e00 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
24e10 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
24e20 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
24e30 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
24e40 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
24e50 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
24e60 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
24e70 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
24e80 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ABORT]..*/.int s
24e90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24ea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24eb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24ec0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
24ed0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24ee0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
24ef0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
24f00 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
24f10 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
24f20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24f30 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
24f40 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
24f50 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
24f60 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
24f70 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
24f80 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
24f90 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
24fa0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
24fb0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
24fc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24fd0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
24fe0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
24ff0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
25000 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
25010 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
25020 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
25030 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
25040 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
25050 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
25060 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
25070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25080 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
25090 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
250a0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
250b0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
250c0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
250d0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
250e0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
250f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25100 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
25110 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
25120 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
25130 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
25140 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
25150 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
25160 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
25170 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25180 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
25190 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
251a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
251b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
251c0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
251d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
251e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
251f0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
25200 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
25210 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
25220 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
25230 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
25240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
25250 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
25260 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
25270 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
25280 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
25290 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
252a0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
252b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
252c0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
252d0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
252e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
252f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
25300 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
25310 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
25320 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
25330 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
25340 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
25350 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25360 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25370 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
25380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25390 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
253a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
253b0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74  }.**.** ^These t
253c0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
253d0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
253e0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
253f0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
25400 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
25410 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
25420 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
25430 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
25440 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
25450 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
25460 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25470 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
25480 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
25490 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
254a0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
254b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
254c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
254d0 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
254e0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
254f0 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
25500 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
25510 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25520 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
25530 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
25540 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25550 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  )..**.** ^The fi
25560 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
25570 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
25580 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
25590 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
255a0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
255b0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
255c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
255d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
255e0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
255f0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
25600 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
25610 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
25620 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
25630 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
25640 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
25650 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
25660 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25670 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
25680 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25690 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
256a0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
256b0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
256c0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
256d0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
256e0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a  , exclusive of.*
256f0 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  * the zero-termi
25700 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
25710 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
25720 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
25730 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
25740 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74  acters.  ^Any at
25750 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
25760 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
25770 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
25780 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
25790 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
257a0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
257b0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
257c0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
257d0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
257e0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
257f0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
25800 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
25810 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
25820 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
25830 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
25840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
25850 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
25860 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
25870 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
25880 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
25890 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
258a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
258b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
258c0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
258d0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
258e0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
258f0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
25900 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
25910 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
25920 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
25930 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
25940 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
25950 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
25960 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
25970 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
25980 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
25990 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
259a0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
259b0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
259c0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
259d0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
259e0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
259f0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
25a00 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
25a10 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
25a20 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
25a30 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
25a40 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
25a50 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
25a60 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
25a70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
25a80 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
25a90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25aa0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
25ab0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
25ac0 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
25ad0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
25ae0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
25af0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
25b00 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
25b10 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
25b20 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
25b30 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25b40 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
25b50 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
25b60 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
25b70 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
25b80 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
25b90 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
25ba0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
25bb0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
25bc0 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
25bd0 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
25be0 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
25bf0 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
25c00 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
25c10 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25c20 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
25c30 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
25c40 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
25c50 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
25c60 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
25c70 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
25c80 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
25c90 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
25ca0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
25cb0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
25cc0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
25cd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .)^.**.** The se
25ce0 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
25cf0 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
25d00 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
25d10 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
25d20 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
25d30 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
25d40 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
25d50 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
25d60 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
25d70 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
25d80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
25d90 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
25da0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
25db0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
25dc0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
25dd0 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
25de0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
25df0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
25e00 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
25e10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
25e20 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
25e30 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
25e40 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
25e50 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
25e60 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
25e70 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
25e80 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
25e90 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
25ea0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
25eb0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
25ec0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
25ed0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  tion callbacks..
25ee0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
25ef0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
25f00 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
25f10 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
25f20 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
25f30 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
25f40 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
25f50 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
25f60 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
25f70 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
25f80 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
25f90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
25fa0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
25fb0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
25fc0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
25fd0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
25fe0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
25ff0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
26000 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
26010 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
26020 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
26030 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
26040 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
26050 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
26060 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26070 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
26080 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
26090 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
260a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
260b0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
260c0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
260d0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
260e0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
260f0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
26100 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
26110 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
26120 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
26130 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
26140 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
26150 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
26160 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
26170 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
26180 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
26190 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
261a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
261b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
261c0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
261d0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
261e0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
261f0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
26200 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
26210 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
26220 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26230 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ns..** ^The firs
26240 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
26250 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
26260 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
26270 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
26280 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
26290 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
262a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
262b0 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
262c0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53  same name..** ^S
262d0 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
262e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
262f0 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
26300 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
26310 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
26320 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26330 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
26340 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
26350 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
26360 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
26370 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
26380 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
26390 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
263a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
263b0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
263c0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
263d0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
263e0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
263f0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
26400 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
26410 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26420 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
26430 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
26440 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
26450 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
26460 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
26470 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
26480 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26490 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
264a0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
264b0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
264c0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
264d0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
264e0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
264f0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
26500 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
26510 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26520 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
26530 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
26540 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
26550 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
26560 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
26570 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
26580 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
26590 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
265a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
265b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
265c0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
265d0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
265e0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
265f0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
26600 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
26610 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
26620 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
26630 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
26640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
26650 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26660 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
26670 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
26680 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
26690 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
266a0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
266b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
266c0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
266d0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
266e0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
266f0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
26700 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
26710 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
26720 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
26730 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
26740 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
26750 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26760 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
26770 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
26780 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
26790 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
267a0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
267b0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
267c0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
267d0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
267e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
267f0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
26800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26810 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
26820 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
26830 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
26840 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
26850 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
26860 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
26870 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
26880 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
26890 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
268a0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
268b0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
268c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
268d0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
268e0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
268f0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
26900 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
26910 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
26920 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
26930 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
26940 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
26950 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
26960 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
26970 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
26980 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
26990 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
269a0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
269b0 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
269c0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
269d0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
269e0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
269f0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
26a00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
26a10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26a20 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
26a30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
26a40 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
26a50 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
26a60 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
26a70 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
26a80 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
26a90 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
26aa0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
26ab0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26ac0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
26ad0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
26ae0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
26af0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
26b00 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
26b10 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
26b20 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26b30 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
26b40 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
26b50 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
26b60 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
26b70 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
26b80 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
26b90 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
26ba0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
26bb0 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
26bc0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
26bd0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
26be0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
26bf0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
26c00 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
26c10 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
26c20 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
26c30 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
26c40 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
26c50 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
26c60 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
26c70 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
26c80 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
26c90 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
26ca0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
26cb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26cc0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
26cd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26ce0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
26cf0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
26d00 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
26d10 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
26d20 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
26d30 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
26d40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
26d50 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
26d60 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
26d70 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
26d80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26d90 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
26da0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
26db0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26dc0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
26dd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
26de0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
26df0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26e00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
26e10 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
26e20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
26e30 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
26e40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26e50 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
26e60 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
26e70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26e80 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
26e90 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
26ea0 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
26eb0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26ec0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
26ed0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
26ee0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
26ef0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
26f00 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
26f10 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
26f20 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
26f30 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
26f40 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
26f50 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
26f60 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
26f70 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
26f80 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26f90 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
26fa0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
26fb0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
26fc0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
26fd0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
26fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26ff0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27000 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
27010 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
27020 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
27030 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
27040 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
27050 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
27060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27070 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
27080 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27090 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
270a0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
270b0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
270c0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
270d0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
270e0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
270f0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
27100 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
27110 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
27120 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
27130 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
27140 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
27150 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
27160 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
27170 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
27180 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
27190 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
271a0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
271b0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
271c0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
271d0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
271e0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
271f0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
27200 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
27210 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
27220 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
27230 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
27240 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
27250 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
27260 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
27270 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
27280 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
27290 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
272a0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
272b0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
272c0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
272d0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
272e0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
272f0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
27300 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
27310 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
27320 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
27330 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
27340 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
27350 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
27360 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
27370 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
27380 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
27390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
273a0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
273b0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
273c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
273d0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
273e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
273f0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
27400 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27410 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
27420 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
27430 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
27440 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
27450 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
27460 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
27470 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
27480 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27490 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
274a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
274b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
274c0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
274d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
274e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
274f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27500 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
27510 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
27520 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
27530 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
27540 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
27550 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
27560 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
27570 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
27580 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
27590 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
275a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
275b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
275c0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
275d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
275e0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
275f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
27600 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27610 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
27620 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
27630 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
27640 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
27650 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
27670 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27680 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27690 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
276a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
276b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
276c0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
276d0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
276e0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
276f0 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67  ementions of agg
27700 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
27710 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
27720 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
27730 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
27740 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
27750 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
27760 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
27770 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27780 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
27790 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
277a0 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
277b0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
277c0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
277d0 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
277e0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
277f0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
27800 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
27810 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
27820 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
27830 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
27840 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
27850 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
27860 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27870 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
27880 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
27890 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
278a0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
278b0 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
278c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
278d0 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
278e0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
278f0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
27900 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
27910 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
27920 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
27930 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
27940 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
27950 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
27960 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
27970 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
27980 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
27990 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
279a0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
279b0 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
279c0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
279d0 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
279e0 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
279f0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
27a00 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
27a10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27a20 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
27a30 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
27a40 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
27a50 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
27a60 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
27a70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
27a80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27a90 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
27aa0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
27ab0 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
27ac0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
27ad0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
27ae0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
27af0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
27b00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
27b10 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
27b20 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
27b30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27b40 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
27b50 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
27b60 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
27b70 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
27b80 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
27b90 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
27ba0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
27bb0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
27bc0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27bd0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
27be0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
27bf0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
27c00 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
27c10 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
27c20 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
27c30 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
27c40 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
27c50 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
27c60 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
27c70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27c80 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
27c90 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
27ca0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
27cb0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
27cc0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
27cd0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
27ce0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
27cf0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
27d00 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
27d10 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
27d20 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
27d30 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
27d40 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
27d50 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
27d60 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
27d70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
27d80 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
27d90 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
27da0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
27db0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
27dc0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
27dd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
27de0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
27df0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27e00 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
27e10 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
27e20 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
27e30 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
27e40 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
27e50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27e60 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
27e70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27e80 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
27e90 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
27ea0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
27eb0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
27ec0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
27ed0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
27ee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27ef0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
27f00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27f10 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
27f20 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
27f30 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
27f40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27f50 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
27f60 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
27f70 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
27f80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
27f90 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
27fa0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
27fb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27fc0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27fd0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
27fe0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
27ff0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
28000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28010 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
28020 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
28030 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
28040 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
28050 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
28060 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
28070 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
28080 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
28090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
280a0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
280b0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
280c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
280d0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
280e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
280f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
28100 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
28110 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
28120 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
28130 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
28140 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
28150 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
28160 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
28170 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28180 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
28190 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
281a0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
281b0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
281c0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
281d0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
281e0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
281f0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
28200 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
28210 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
28220 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
28230 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
28240 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
28250 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
28260 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
28270 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
28280 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
28290 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
282a0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
282b0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
282c0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
282d0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
282e0 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
282f0 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
28300 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
28310 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
28320 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
28330 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
28340 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
28350 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
28360 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
28370 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
28380 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
28390 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
283a0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
283b0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
283c0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
283d0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
283e0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
283f0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
28400 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
28410 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
28420 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
28430 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
28440 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
28450 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
28460 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
28470 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
28480 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
28490 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
284a0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
284b0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
284c0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
284d0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
284e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
284f0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
28500 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
28510 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
28520 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28530 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
28540 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
28550 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
28560 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
28570 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
28580 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
28590 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
285a0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
285b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
285c0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
285d0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
285e0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
285f0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
28600 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
28610 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
28620 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
28630 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
28640 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
28650 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
28660 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
28670 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
28680 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
28690 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
286a0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
286b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
286c0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
286d0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
286e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
286f0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
28700 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
28710 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
28720 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
28730 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
28740 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
28750 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
28760 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
28770 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
28780 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
28790 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
287a0 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
287b0 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
287c0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
287d0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
287e0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
287f0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
28800 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
28810 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
28820 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
28830 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
28840 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
28850 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
28860 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
28870 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
28880 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
28890 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
288a0 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
288b0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
288c0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
288d0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
288e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
288f0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
28900 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
28910 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
28920 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
28930 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
28940 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
28950 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
28960 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
28970 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
28980 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
28990 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
289a0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
289b0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
289c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
289d0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
289e0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
289f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
28a00 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
28a10 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28a20 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
28a30 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
28a40 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
28a50 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28a60 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
28a70 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
28a80 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
28a90 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
28aa0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
28ab0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
28ac0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
28ad0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
28ae0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
28af0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
28b00 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
28b10 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
28b20 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
28b30 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
28b40 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
28b50 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
28b60 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
28b70 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
28b80 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
28b90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
28ba0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
28bb0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
28bc0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
28bd0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
28be0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
28bf0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
28c00 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
28c10 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
28c20 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
28c30 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
28c40 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
28c50 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
28c60 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
28c70 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28c80 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
28c90 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
28ca0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
28cb0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
28cc0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
28cd0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
28ce0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
28cf0 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
28d00 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
28d10 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
28d20 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
28d30 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
28d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
28d50 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
28d60 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28d70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
28d80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
28d90 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
28da0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
28db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
28dc0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
28dd0 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
28de0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
28df0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
28e00 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
28e10 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
28e20 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
28e30 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
28e40 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
28e50 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
28e60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28e70 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
28e80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28e90 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
28ea0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28eb0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
28ec0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
28ed0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
28ee0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
28ef0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
28f00 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
28f10 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
28f20 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
28f30 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
28f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
28f50 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
28f60 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
28f70 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
28f80 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
28f90 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
28fa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
28fb0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
28fc0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
28fd0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
28fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28ff0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29000 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
29010 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
29020 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
29030 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
29040 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
29050 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
29060 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
29070 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
29080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29090 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
290a0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
290b0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
290c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
290d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
290e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
290f0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
29100 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
29110 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
29120 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
29130 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29140 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
29150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29160 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
29170 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29180 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
29190 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
291a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
291b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
291c0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
291d0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
291e0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
291f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
29200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29210 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
29220 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29230 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
29240 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
29250 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
29260 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
29270 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
29280 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
29290 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
292a0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
292b0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
292c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
292d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
292e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
292f0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
29300 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
29310 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
29320 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
29330 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
29340 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
29350 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
29360 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
29370 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
29380 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
29390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
293a0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
293b0 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
293c0 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
293d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
293e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
293f0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
29400 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29410 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
29420 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
29430 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
29440 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
29450 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
29460 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
29470 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
29480 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29490 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
294a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
294b0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
294c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
294d0 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
294e0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
294f0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
29500 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
29510 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
29520 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29530 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
29540 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
29550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29560 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
29570 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29580 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
29590 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
295a0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
295b0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
295c0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
295d0 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
295e0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
295f0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
29600 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
29610 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
29620 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
29630 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
29640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29650 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
29660 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
29670 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
29680 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
29690 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
296a0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
296b0 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
296c0 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
296d0 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
296e0 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
296f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
29700 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29710 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
29720 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29730 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
29740 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
29750 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
29760 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29770 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
29780 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
29790 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
297a0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
297b0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
297c0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
297d0 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
297e0 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
297f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29800 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
29810 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
29820 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
29830 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
29840 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
29850 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
29860 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29870 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29880 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29890 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
298a0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
298b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
298c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
298d0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
298e0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
298f0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
29900 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
29910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29920 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
29930 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
29940 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
29950 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29960 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29970 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
29980 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29990 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
299a0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
299b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
299c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
299d0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
299e0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
299f0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
29a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29a10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29a20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
29a30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
29a40 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
29a50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29a60 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
29a70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
29a80 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
29a90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
29aa0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
29ab0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
29ac0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
29ad0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29ae0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
29af0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
29b00 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
29b10 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
29b20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
29b30 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
29b40 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
29b50 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
29b60 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
29b70 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
29b80 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
29b90 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
29ba0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
29bb0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
29bc0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
29bd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29be0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
29bf0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
29c00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
29c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29c20 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
29c30 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
29c40 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
29c50 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
29c60 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
29c70 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
29c80 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
29c90 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
29ca0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
29cb0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29cc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29cd0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
29ce0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
29cf0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
29d00 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
29d10 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
29d20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
29d30 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29d40 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
29d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29d60 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
29d70 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
29d80 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
29d90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29da0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29db0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
29dc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29dd0 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
29de0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
29df0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
29e00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
29e10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
29e20 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
29e30 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
29e40 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
29e50 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
29e60 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
29e70 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29e80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29e90 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29ea0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
29eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
29ec0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
29ed0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
29ee0 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
29ef0 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
29f00 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
29f10 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
29f20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
29f30 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
29f40 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
29f50 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
29f60 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
29f70 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
29f80 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
29f90 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
29fa0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
29fb0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
29fc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
29fd0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
29fe0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
29ff0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
2a000 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2a010 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2a020 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
2a030 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
2a040 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
2a050 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
2a060 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
2a070 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
2a080 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2a090 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
2a0a0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2a0b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a0c0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2a0d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2a0e0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2a0f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a100 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2a110 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
2a120 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a130 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a140 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
2a150 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2a160 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2a170 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a180 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
2a190 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a1a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
2a1b0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
2a1c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2a1d0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2a1e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2a1f0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2a200 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2a210 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a220 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2a230 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2a240 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
2a250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a260 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2a270 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2a280 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2a290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a2a0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2a2b0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2a2c0 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2a2d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2a2e0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2a2f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2a300 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2a310 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2a320 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2a330 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2a340 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
2a350 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2a360 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a370 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a380 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
2a390 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2a3a0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2a3b0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a3c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
2a3d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a3e0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
2a3f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2a400 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2a410 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2a420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a430 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
2a440 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
2a450 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a460 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
2a470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a480 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
2a490 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a4a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
2a4b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2a4c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
2a4d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a4e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2a4f0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
2a500 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2a510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2a520 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
2a530 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2a540 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a550 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
2a560 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2a570 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a580 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
2a590 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2a5a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a5b0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
2a5c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2a5d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
2a5e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a5f0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
2a600 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2a610 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a620 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a630 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2a640 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a650 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a660 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a670 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a680 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2a690 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a6a0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a6b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a6c0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2a6d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2a6e0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2a6f0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2a700 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a710 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2a720 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2a730 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2a740 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2a750 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a760 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2a770 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
2a780 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
2a790 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2a7a0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2a7b0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
2a7c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
2a7d0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
2a7e0 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
2a7f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2a800 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
2a810 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
2a820 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
2a830 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2a840 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
2a850 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2a860 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2a870 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2a880 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
2a890 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
2a8a0 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
2a8b0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2a8c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a8d0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2a8e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2a8f0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2a900 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2a910 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
2a920 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2a930 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73  6(). ^In all cas
2a940 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
2a950 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2a960 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2a970 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2a980 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2a990 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
2a9a0 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
2a9b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2a9c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
2a9d0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2a9e0 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
2a9f0 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
2aa00 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
2aa10 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
2aa20 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
2aa30 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
2aa40 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
2aa50 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
2aa60 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
2aa70 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
2aa80 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2aa90 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61   ^The.** third a
2aaa0 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
2aab0 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
2aac0 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  F16] to indicate
2aad0 20 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e   that the routin
2aae0 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69  e.** expects poi
2aaf0 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d  nters to be UTF-
2ab00 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  16 strings in th
2ab10 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2ab20 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61  der, or the.** a
2ab30 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b  rgument can be [
2ab40 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2ab50 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20  GNED] if the.** 
2ab60 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
2ab70 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
2ab80 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
2ab90 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
2aba0 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
2abb0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2abc0 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  r..**.** A point
2abd0 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73  er to the user s
2abe0 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2abf0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2ac00 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61  s the fifth.** a
2ac10 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74  rgument.  ^If it
2ac20 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
2ac30 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
2ac40 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
2ac50 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2ac60 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
2ac70 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
2ac80 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61  anymore)..** ^Ea
2ac90 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
2aca0 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
2acb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2acc0 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2acd0 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
2ace0 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
2acf0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
2ad00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2ad10 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
2ad20 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
2ad30 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2ad40 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2ad50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2ad60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61  .**.** ^The rema
2ad70 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
2ad80 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2ad90 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
2ada0 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
2adb0 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
2adc0 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
2add0 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
2ade0 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
2adf0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
2ae00 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
2ae10 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
2ae20 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
2ae30 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2ae40 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
2ae50 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69  ered.  The appli
2ae60 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
2ae70 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
2ae80 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
2ae90 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
2aea0 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
2aeb0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
2aec0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
2aed0 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
2aee0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2aef0 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
2af00 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
2af10 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e  TRING2)..**.** ^
2af20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
2af30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2af40 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
2af50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2af60 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
2af70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
2af80 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
2af90 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
2afa0 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
2afb0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e  he collation.  ^
2afc0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2afd0 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
2afe0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
2aff0 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
2b000 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2b010 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2b020 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
2b030 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
2b040 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b050 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
2b060 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  ** ^Collations a
2b070 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
2b080 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
2b090 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
2b0a0 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63  alls to the.** c
2b0b0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2b0c0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
2b0d0 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73  hen the [databas
2b0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2b0f0 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67   closed.** using
2b100 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2b110 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2b120 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
2b130 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2b140 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2b150 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2b160 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
2b170 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b180 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
2b190 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2b1a0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2b1b0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2b1c0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2b1d0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2b1e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2b1f0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
2b200 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2b210 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
2b220 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2b230 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2b240 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2b250 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2b260 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2b270 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b280 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b290 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2b2a0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2b2b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2b2c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b2d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b2e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
2b2f0 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
2b300 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2b310 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2b320 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b330 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b340 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2b350 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2b360 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2b370 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2b380 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2b390 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2b3a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2b3b0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2b3c0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2b3d0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2b3e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2b3f0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2b400 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2b410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b420 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2b430 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2b440 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2b450 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2b460 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2b470 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2b480 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2b490 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2b4a0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b4b0 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2b4c0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2b4d0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2b4e0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2b4f0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2b500 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2b510 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2b520 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b530 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2b540 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2b550 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2b560 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2b570 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2b580 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2b590 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2b5a0 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2b5b0 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2b5c0 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2b5d0 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2b5e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2b5f0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2b600 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2b610 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2b620 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2b630 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2b640 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b650 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2b660 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b670 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2b680 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2b690 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2b6a0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2b6b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2b6c0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b6d0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2b6e0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2b6f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2b700 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2b710 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2b720 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2b730 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2b740 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b750 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2b760 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b770 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2b780 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2b790 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2b7a0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2b7b0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2b7c0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2b7d0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2b7e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2b7f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b800 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2b810 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b820 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2b830 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b840 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2b850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2b860 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2b870 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2b880 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2b890 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2b8a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2b8b0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2b8c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2b8d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2b8e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2b8f0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2b900 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2b910 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2b920 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2b930 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2b940 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2b950 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2b960 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2b970 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2b980 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2b990 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2b9a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2b9b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2b9c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2b9d0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2b9e0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2b9f0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2ba00 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2ba10 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2ba20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2ba30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ba40 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2ba50 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2ba60 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2ba70 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2ba80 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2ba90 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2baa0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2bab0 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2bac0 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2bad0 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2bae0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2baf0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2bb00 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2bb10 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2bb20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2bb30 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2bb40 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2bb50 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2bb60 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2bb70 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2bb80 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2bb90 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2bba0 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2bbb0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2bbc0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2bbd0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2bbe0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2bbf0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2bc00 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2bc10 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2bc20 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2bc30 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2bc40 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2bc50 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2bc60 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2bc70 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2bc80 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2bc90 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2bca0 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2bcb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2bcc0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2bcd0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2bce0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2bcf0 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2bd00 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2bd10 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2bd20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2bd30 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2bd40 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2bd50 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2bd60 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2bd70 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2bd80 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2bd90 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2bda0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2bdb0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2bdc0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2bdd0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2bde0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2bdf0 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2be00 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2be10 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ort Time.**.** ^
2be20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2be30 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2be40 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2be50 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2be60 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2be70 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2be80 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2be90 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2bea0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2beb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  .**.** ^If the o
2bec0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2bed0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2bee0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2bef0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2bf00 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2bf10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2bf20 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2bf30 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2bf40 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2bf50 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  ^The number of m
2bf60 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2bf70 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2bf80 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2bf90 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2bfa0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2bfb0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
2bfc0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2bfd0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2bfe0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2bff0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2c000 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2c010 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2c020 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c030 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2c040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2c050 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2c060 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2c070 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2c080 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2c090 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2c0a0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2c0b0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2c0c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2c0d0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2c0e0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2c0f0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2c100 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2c110 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2c120 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2c130 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2c140 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2c150 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2c160 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2c170 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2c180 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c190 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2c1a0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2c1b0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2c1c0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2c1d0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2c1e0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2c1f0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2c200 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2c210 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2c220 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2c230 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2c240 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2c250 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2c260 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2c270 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2c280 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2c290 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2c2a0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2c2b0 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2c2c0 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2c2d0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2c2e0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2c2f0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2c300 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2c310 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2c320 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2c330 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2c340 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2c350 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2c360 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2c370 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2c380 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2c390 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2c3a0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c3b0 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2c3c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2c3d0 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2c3e0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2c3f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2c400 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2c410 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2c420 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2c430 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c440 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2c450 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2c460 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2c470 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2c480 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2c490 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2c4a0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2c4b0 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2c4c0 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2c4d0 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2c4e0 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2c4f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2c500 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2c510 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2c520 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2c530 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2c540 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2c550 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2c560 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2c570 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2c580 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2c590 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2c5a0 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2c5b0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c5c0 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2c5d0 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2c5e0 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
2c5f0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
2c600 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
2c610 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
2c620 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2c630 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2c640 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2c650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c660 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2c670 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2c680 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2c690 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2c6a0 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2c6b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2c6c0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2c6d0 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2c6e0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
2c6f0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2c700 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
2c710 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2c720 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2c730 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2c740 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
2c750 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2c760 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
2c770 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2c780 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2c790 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2c7a0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2c7b0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2c7c0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2c7d0 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2c7e0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
2c7f0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
2c800 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
2c810 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
2c820 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
2c830 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
2c840 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
2c850 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
2c860 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
2c870 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
2c880 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2c890 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
2c8a0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
2c8b0 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
2c8c0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2c8d0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2c8e0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2c8f0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2c900 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2c910 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
2c920 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
2c930 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
2c940 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
2c950 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2c960 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
2c970 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
2c980 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
2c990 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
2c9a0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2c9b0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2c9c0 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2c9d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c9e0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2c9f0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2ca00 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ca10 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
2ca20 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2ca30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ca40 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2ca50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2ca60 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
2ca70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ca80 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
2ca90 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
2caa0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2cab0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2cac0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2cad0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2cae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2caf0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2cb00 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2cb10 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2cb20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2cb30 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2cb40 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2cb50 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2cb60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2cb70 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2cb80 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2cb90 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2cba0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2cbb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cbc0 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
2cbd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cbe0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
2cbf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cc00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2cc10 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2cc20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2cc30 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2cc40 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2cc50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cc60 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
2cc70 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
2cc80 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
2cc90 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2cca0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
2ccb0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2ccc0 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
2ccd0 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
2cce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ccf0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
2cd00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2cd10 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
2cd20 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
2cd30 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
2cd40 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
2cd50 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
2cd60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
2cd70 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
2cd80 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2cd90 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
2cda0 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
2cdb0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
2cdc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
2cdd0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
2cde0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
2cdf0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
2ce00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2ce10 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2ce20 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2ce30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ce40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce50 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2ce60 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2ce70 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2ce80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ce90 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
2cea0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2ceb0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2cec0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2ced0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2cee0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2cef0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
2cf00 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
2cf10 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2cf20 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2cf30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2cf40 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2cf50 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2cf60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2cf70 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2cf80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
2cf90 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2cfa0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2cfb0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2cfc0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2cfd0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2cfe0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2cff0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2d000 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
2d010 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2d020 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2d030 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
2d040 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
2d050 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d060 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d070 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d080 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
2d090 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2d0a0 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2d0b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
2d0c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2d0d0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2d0e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2d0f0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2d100 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2d110 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2d120 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2d130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
2d140 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
2d150 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
2d160 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
2d170 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
2d180 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
2d190 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2d1a0 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
2d1b0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2d1c0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2d1d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d1e0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2d1f0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2d200 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
2d210 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
2d220 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2d230 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d240 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2d250 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2d260 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2d270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d280 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2d290 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
2d2a0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2d2b0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2d2c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2d2d0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2d2e0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2d2f0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2d300 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2d310 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2d320 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
2d330 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
2d340 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
2d350 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
2d360 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2d370 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2d390 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2d3a0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2d3b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2d3c0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2d3d0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2d3e0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2d3f0 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
2d400 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2d410 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2d420 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
2d430 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2d440 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2d450 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2d460 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2d470 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2d480 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2d490 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
2d4a0 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
2d4b0 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
2d4c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
2d4d0 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
2d4e0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
2d4f0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
2d500 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
2d510 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2d520 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
2d530 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
2d540 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
2d550 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
2d560 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
2d570 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
2d580 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
2d590 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
2d5a0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2d5b0 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2d5c0 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2d5d0 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2d5e0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2d5f0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2d600 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2d610 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2d620 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2d630 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2d640 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2d650 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
2d660 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2d670 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2d680 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2d690 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
2d6a0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2d6b0 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
2d6c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d6d0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
2d6e0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2d6f0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2d700 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2d710 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2d720 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2d730 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2d740 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2d750 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2d760 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2d770 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2d780 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2d790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d7a0 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2d7b0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2d7c0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2d7d0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2d7e0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2d7f0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2d800 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2d810 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2d820 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2d830 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2d840 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2d850 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2d860 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2d870 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2d880 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2d890 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2d8a0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2d8b0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2d8c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2d8d0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d8e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d8f0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2d900 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2d910 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2d920 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2d930 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2d940 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2d950 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2d960 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2d970 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2d980 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2d990 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2d9a0 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2d9b0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2d9c0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2d9d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2d9e0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2d9f0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2da00 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2da10 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2da20 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2da30 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2da40 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2da50 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2da60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2da70 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2da80 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2da90 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2daa0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2dab0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2dac0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2dad0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2dae0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2daf0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2db00 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2db10 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2db20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2db30 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2db40 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2db50 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2db60 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2db70 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2db80 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2db90 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2dba0 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2dbb0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2dbc0 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2dbd0 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2dbe0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2dbf0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2dc00 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2dc10 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2dc20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2dc30 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2dc40 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2dc50 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2dc60 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2dc70 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2dc80 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2dc90 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2dca0 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2dcb0 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2dcc0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2dcd0 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2dce0 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2dcf0 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2dd00 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2dd10 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2dd20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2dd30 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2dd40 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2dd50 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2dd60 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2dd70 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2dd80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2dd90 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2dda0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2ddb0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2ddc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2ddd0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2dde0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2ddf0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2de00 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2de10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2de20 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2de30 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2de40 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2de50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2de60 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2de70 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2de80 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2de90 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2dea0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2deb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2dec0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2ded0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2dee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2def0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2df00 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2df10 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2df20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2df30 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2df40 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2df50 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2df60 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2df70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2df80 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2df90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dfa0 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2dfb0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2dfc0 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2dfd0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2dfe0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2dff0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e000 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2e010 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2e020 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2e030 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2e040 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2e050 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2e060 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2e070 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2e080 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2e090 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2e0a0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2e0b0 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2e0c0 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2e0d0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2e0e0 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2e0f0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2e100 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2e110 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2e120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2e130 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2e140 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2e150 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2e160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2e170 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2e180 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2e190 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2e1a0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2e1b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2e1c0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2e1d0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2e1e0 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2e1f0 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2e200 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2e210 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2e220 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2e230 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2e240 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2e250 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2e260 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2e270 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2e280 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2e290 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2e2a0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2e2b0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2e2c0 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2e2d0 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2e2e0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2e2f0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2e300 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2e310 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2e320 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2e330 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2e340 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2e350 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2e360 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e370 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2e380 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2e390 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2e3a0 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2e3b0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2e3c0 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2e3d0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2e3e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2e3f0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2e400 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2e410 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2e420 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2e430 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2e440 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2e450 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2e460 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2e470 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2e480 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2e490 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2e4a0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2e4b0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2e4c0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2e4d0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2e4e0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2e4f0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2e500 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2e510 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2e520 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2e530 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2e540 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2e550 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2e560 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2e570 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2e580 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2e590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2e5a0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2e5b0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2e5c0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2e5d0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2e5e0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2e5f0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2e600 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2e610 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2e620 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2e630 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2e640 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2e650 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2e660 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2e670 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2e680 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2e690 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2e6a0 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2e6b0 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2e6c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e6d0 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2e6e0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2e6f0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2e700 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2e710 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2e720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2e730 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2e740 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e750 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2e760 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2e770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e780 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2e790 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2e7a0 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2e7b0 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2e7c0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2e7d0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2e7e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2e7f0 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2e800 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2e810 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2e820 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2e830 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2e840 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2e850 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e860 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2e870 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2e880 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2e890 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2e8a0 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2e8b0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2e8c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2e8d0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2e8e0 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2e8f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e900 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2e910 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2e920 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2e930 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2e940 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2e950 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2e960 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2e970 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2e980 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2e990 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2e9a0 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2e9b0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2e9c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2e9d0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2e9e0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2e9f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2ea00 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2ea10 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2ea20 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2ea30 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2ea40 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2ea50 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2ea60 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2ea70 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2ea80 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2ea90 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2eaa0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2eab0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2eac0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2ead0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2eae0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2eaf0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2eb00 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2eb10 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2eb20 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2eb30 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2eb40 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2eb50 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2eb60 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2eb70 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2eb80 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2eb90 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2eba0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2ebb0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2ebc0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2ebd0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2ebe0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2ebf0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2ec00 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2ec10 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2ec20 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2ec30 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2ec40 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2ec50 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2ec60 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2ec70 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2ec80 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2ec90 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2eca0 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2ecb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2ecc0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2ecd0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2ece0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2ecf0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2ed00 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2ed10 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2ed20 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2ed30 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2ed40 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2ed50 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ed60 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2ed70 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2ed80 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2ed90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2eda0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2edb0 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2edc0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2edd0 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2ede0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2edf0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2ee00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ee10 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2ee20 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2ee30 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2ee40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2ee50 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
2ee60 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2ee70 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2ee80 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2ee90 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2eea0 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
2eeb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2eec0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2eed0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2eee0 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2eef0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
2ef00 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2ef10 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2ef20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2ef30 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2ef40 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2ef50 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
2ef60 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
2ef70 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
2ef80 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
2ef90 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
2efa0 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
2efb0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
2efc0 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
2efd0 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
2efe0 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
2eff0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2f000 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f010 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2f020 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
2f030 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
2f040 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
2f050 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
2f060 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
2f070 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
2f080 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
2f090 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
2f0a0 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2f0b0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2f0c0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2f0d0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2f0e0 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2f0f0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2f100 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2f110 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
2f120 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2f130 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2f140 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2f150 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2f160 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2f170 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2f180 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
2f190 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2f1a0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2f1b0 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2f1c0 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2f1d0 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2f1e0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2f1f0 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2f200 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2f210 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2f220 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2f230 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2f240 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2f250 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2f260 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2f270 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2f280 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2f290 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2f2a0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2f2b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2f2c0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f2d0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f2e0 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2f2f0 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2f300 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2f310 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f320 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f330 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2f340 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2f350 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2f360 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
2f370 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2f380 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2f390 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2f3a0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2f3b0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2f3c0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2f3d0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2f3e0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2f3f0 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2f400 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2f410 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f420 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2f430 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2f440 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2f450 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2f460 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2f470 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2f480 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2f490 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2f4a0 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2f4b0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2f4c0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2f4d0 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2f4e0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2f4f0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2f500 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2f510 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2f520 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2f530 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
2f540 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
2f550 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
2f560 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2f570 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
2f580 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2f590 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2f5a0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
2f5b0 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2f5c0 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2f5d0 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2f5e0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2f5f0 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2f600 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2f610 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2f620 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2f630 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2f640 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
2f650 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
2f660 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
2f670 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
2f680 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
2f690 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
2f6a0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
2f6b0 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
2f6c0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
2f6d0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
2f6e0 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
2f6f0 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
2f700 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
2f710 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
2f720 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
2f730 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f740 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
2f750 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
2f760 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2f770 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
2f780 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2f790 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f7a0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f7b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f7c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f7d0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f7e0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f7f0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
2f800 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
2f810 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
2f820 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
2f830 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2f840 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
2f850 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2f860 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2f870 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f880 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
2f890 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2f8a0 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
2f8b0 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
2f8c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2f8d0 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
2f8e0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
2f8f0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2f900 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
2f910 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
2f920 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
2f930 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2f940 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
2f950 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
2f960 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
2f970 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
2f980 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
2f990 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2f9a0 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
2f9b0 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
2f9c0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
2f9d0 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
2f9e0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2f9f0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
2fa00 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
2fa10 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
2fa20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2fa30 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2fa40 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
2fa50 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
2fa60 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
2fa70 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
2fa80 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2fa90 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2faa0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2fab0 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2fac0 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2fad0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2fae0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2faf0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2fb00 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2fb10 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2fb20 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2fb30 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
2fb40 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
2fb50 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2fb60 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
2fb70 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2fb80 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2fb90 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2fba0 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
2fbb0 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
2fbc0 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
2fbd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2fbe0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2fbf0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fc00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
2fc10 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
2fc20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2fc30 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
2fc40 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
2fc50 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
2fc60 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
2fc70 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
2fc80 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2fc90 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2fca0 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2fcb0 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
2fcc0 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2fcd0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2fce0 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2fcf0 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
2fd00 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2fd10 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
2fd20 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
2fd30 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
2fd40 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
2fd50 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
2fd60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
2fd70 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2fd80 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2fd90 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
2fda0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2fdb0 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
2fdc0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
2fdd0 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
2fde0 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
2fdf0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2fe00 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
2fe10 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2fe20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
2fe30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
2fe40 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
2fe50 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2fe60 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
2fe70 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
2fe80 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
2fe90 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
2fea0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2feb0 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
2fec0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
2fed0 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
2fee0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
2fef0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
2ff00 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
2ff10 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
2ff20 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
2ff30 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
2ff40 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
2ff50 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
2ff60 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
2ff70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff80 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
2ff90 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
2ffa0 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
2ffb0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
2ffc0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
2ffd0 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
2ffe0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
2fff0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
30000 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
30010 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
30020 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
30030 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
30040 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
30050 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
30060 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
30070 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
30080 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
30090 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
300a0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
300b0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
300c0 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
300d0 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
300e0 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
300f0 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
30100 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
30110 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
30120 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
30130 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
30140 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
30150 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
30160 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
30170 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
30180 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
30190 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
301a0 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
301b0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
301c0 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
301d0 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
301e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
301f0 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
30200 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
30210 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
30220 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
30230 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
30240 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
30250 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
30260 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
30270 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
30280 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
30290 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
302a0 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
302b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
302c0 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
302d0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
302e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
302f0 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
30300 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
30310 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
30320 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
30330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
30340 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
30350 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
30360 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
30370 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30380 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
30390 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
303a0 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
303b0 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
303c0 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
303d0 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
303e0 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
303f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30400 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
30410 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
30420 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
30430 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
30440 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
30450 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
30460 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
30470 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
30480 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
30490 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
304a0 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
304b0 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
304c0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
304d0 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
304e0 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
304f0 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
30500 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30510 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
30520 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
30530 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
30540 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30550 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
30560 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
30570 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
30580 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
30590 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
305a0 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
305b0 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
305c0 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
305d0 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
305e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
305f0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
30600 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
30610 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
30620 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
30630 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
30640 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
30650 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
30660 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30670 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  (void);../*.** T
30680 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
30690 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
306a0 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
306b0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
306c0 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
306d0 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
306e0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
306f0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
30700 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
30710 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
30720 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
30730 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
30740 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
30750 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
30760 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30770 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
30780 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
30790 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
307a0 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
307b0 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
307c0 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
307d0 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
307e0 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
307f0 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
30800 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
30810 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
30820 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
30830 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
30840 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
30850 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
30860 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
30870 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
30880 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
30890 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
308a0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
308b0 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
308c0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
308d0 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
308e0 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
308f0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
30900 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  le Object.** KEY
30910 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
30920 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
30930 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a  able module}.**.
30940 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
30950 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
30960 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
30970 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
30980 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
30990 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
309a0 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
309b0 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
309c0 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
309d0 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
309e0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
309f0 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69  ule..**.** ^A vi
30a00 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30a10 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
30a20 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
30a30 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
30a40 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
30a50 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
30a60 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
30a70 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
30a80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
30a90 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
30aa0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30ab0 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
30ac0 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74  * ^The registrat
30ad0 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
30ae0 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
30af0 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
30b00 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
30b10 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
30b20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30b30 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
30b40 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
30b50 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
30b60 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
30b70 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
30b80 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
30b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30ba0 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
30bb0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
30bc0 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
30bd0 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
30be0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
30bf0 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
30c00 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
30c10 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
30c20 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
30c30 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
30c40 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
30c50 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
30c60 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
30c70 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
30c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
30c90 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
30ca0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
30cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
30cc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
30cd0 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
30ce0 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
30cf0 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
30d00 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
30d10 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
30d20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
30d30 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
30d40 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
30d50 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
30d60 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
30d70 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
30d80 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30d90 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
30da0 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
30db0 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
30dc0 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
30dd0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
30de0 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
30df0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30e00 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
30e10 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
30e20 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
30e30 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
30e40 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
30e50 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
30e60 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
30e70 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
30e80 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
30e90 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
30ea0 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
30eb0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30ec0 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
30ed0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
30ee0 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
30ef0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30f00 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
30f10 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
30f20 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
30f30 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
30f40 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
30f50 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
30f60 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
30f70 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
30f80 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
30f90 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
30fa0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30fb0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
30fc0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
30fd0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
30fe0 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
30ff0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
31000 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
31010 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
31020 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
31030 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
31040 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
31050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31060 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
31070 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31080 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31090 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
310a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
310b0 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
310c0 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
310d0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
310e0 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
310f0 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
31100 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
31110 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
31120 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
31130 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
31140 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
31150 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31160 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
31170 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
31180 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
31190 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
311a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
311b0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
311c0 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
311d0 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
311e0 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
311f0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
31200 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
31210 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
31220 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
31230 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
31240 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
31250 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
31260 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
31270 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
31280 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
31290 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
312a0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
312b0 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
312c0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
312d0 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
312e0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75  .**.** <pre>colu
312f0 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e  mn OP expr</pre>
31300 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
31310 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
31320 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
31330 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74  =.)^  ^(The part
31340 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20  icular operator 
31350 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20  is.** stored in 
31360 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
31370 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78  .)^  ^(The index
31380 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
31390 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
313a0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
313b0 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
313c0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
313d0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
313e0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
313f0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
31400 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
31410 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
31420 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
31430 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
31440 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
31450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
31460 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
31470 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
31480 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
31490 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
314a0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
314b0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
314c0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
314d0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
314e0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
314f0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
31500 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
31510 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
31520 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
31530 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
31540 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
31550 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
31560 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
31570 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
31580 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
31590 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
315a0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
315b0 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
315c0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
315d0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
315e0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
315f0 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
31600 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
31610 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
31620 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
31630 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
31640 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
31650 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
31660 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
31670 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
31680 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
31690 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
316a0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
316b0 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
316c0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
316d0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
316e0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
316f0 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
31700 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
31710 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
31720 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
31730 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
31740 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
31750 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
31760 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
31770 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
31780 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
31790 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
317a0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
317b0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
317c0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
317d0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
317e0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
317f0 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
31800 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
31810 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
31820 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
31830 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
31840 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
31850 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
31860 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
31870 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
31880 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
31890 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
318a0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
318b0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
318c0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
318d0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
318e0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
318f0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
31900 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
31910 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
31920 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
31930 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
31940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
31950 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
31960 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
31970 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
31980 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
31990 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
319a0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
319b0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
319c0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
319d0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
319e0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
319f0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
31a00 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
31a10 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
31a20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
31a30 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
31a40 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31a50 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
31a60 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
31a70 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
31a80 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
31a90 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
31aa0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
31ab0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
31ac0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
31ad0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
31ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31af0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
31b00 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
31b10 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
31b20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
31b30 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
31b40 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
31b50 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
31b60 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
31b70 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
31b80 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
31b90 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
31ba0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
31bb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
31bc0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
31bd0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
31be0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
31bf0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
31c00 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
31c10 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
31c20 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
31c30 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
31c40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31c50 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
31c60 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
31c70 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
31c80 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31c90 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
31ca0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
31cb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
31cc0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
31cd0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
31ce0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
31cf0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
31d00 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
31d10 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
31d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31d30 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
31d40 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
31d50 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
31d60 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
31d70 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
31d80 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
31d90 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
31da0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
31db0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
31dc0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
31dd0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
31de0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
31df0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
31e00 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
31e10 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
31e20 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
31e30 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
31e40 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
31e50 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
31e60 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
31e70 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
31e80 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
31e90 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
31ea0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
31eb0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
31ec0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
31ed0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
31ee0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
31ef0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
31f00 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
31f10 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
31f20 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
31f30 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
31f40 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
31f50 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
31f60 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
31f70 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
31f80 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
31f90 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
31fa0 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
31fb0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
31fc0 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
31fd0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31fe0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
31ff0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
32000 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32010 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
32020 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32030 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
32040 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
32050 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
32060 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
32070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32080 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
32090 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
320a0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
320b0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
320c0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   Implementation.
320d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
320e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
320f0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
32100 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
32110 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
32120 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d   ^Module names m
32130 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
32140 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
32150 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
32160 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
32170 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
32180 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
32190 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
321a0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
321b0 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
321c0 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20  .** ^The module 
321d0 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72  name is register
321e0 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ed on the [datab
321f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32200 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
32210 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
32220 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20  ter.  ^The name 
32230 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73  of the module is
32240 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a   given by the .*
32250 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
32260 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  er.  ^The third 
32270 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
32280 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
32290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
322a0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
322b0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
322c0 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20   ^The fourth.** 
322d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
322e0 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74  arbitrary client
322f0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
32300 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
32310 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  ough.** into the
32320 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
32330 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
32340 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
32350 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a   table module.**
32360 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74   when a new virt
32370 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20  ual table is be 
32380 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72  being created or
32390 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a   reinitialized..
323a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
323b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
323c0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
323d0 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61  has a fifth para
323e0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
323f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
32400 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
32410 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e  the pClientData.
32420 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a    ^SQLite will.*
32430 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  * invoke the des
32440 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
32450 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   (if it is not N
32460 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65  ULL) when SQLite
32470 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  .** no longer ne
32480 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44  eds the pClientD
32490 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ata pointer.  ^T
324a0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
324b0 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
324c0 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
324d0 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
324e0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
324f0 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
32500 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
32510 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
32520 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
32530 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32540 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
32550 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
32560 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
32570 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
32580 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
32590 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
325a0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
325b0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
325c0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
325d0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
325e0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
325f0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
32600 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
32610 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
32620 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
32630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32640 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
32650 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32660 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
32670 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
32680 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
32690 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
326a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
326b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
326c0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
326d0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
326e0 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
326f0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
32700 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
32710 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
32720 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
32730 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
32740 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
32750 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
32760 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
32770 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
32780 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
32790 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
327a0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
327b0 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
327c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
327d0 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
327e0 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
327f0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
32800 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
32810 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
32820 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
32830 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
32840 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
32850 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
32860 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
32870 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
32880 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
32890 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
328a0 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
328b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
328c0 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
328d0 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
328e0 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
328f0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
32900 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
32910 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
32920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32930 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
32940 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
32950 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
32960 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
32970 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
32980 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
32990 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
329a0 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
329b0 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
329c0 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
329d0 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
329e0 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
329f0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
32a00 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
32a10 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
32a20 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
32a30 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
32a40 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
32a50 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
32a60 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
32a70 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
32a80 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
32a90 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
32aa0 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
32ab0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
32ac0 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
32ad0 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
32ae0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
32af0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
32b00 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
32b10 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
32b20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
32b30 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
32b40 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
32b50 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
32b60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
32b70 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
32b80 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
32b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32ba0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
32bb0 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
32bc0 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
32bd0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
32be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32bf0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
32c00 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
32c10 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
32c20 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
32c30 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
32c40 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
32c50 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
32c60 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
32c70 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
32c80 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
32c90 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
32ca0 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
32cb0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
32cc0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
32cd0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
32ce0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
32cf0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
32d00 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
32d10 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
32d20 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
32d30 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
32d40 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
32d50 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
32d60 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
32d70 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
32d80 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
32d90 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
32da0 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
32db0 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
32dc0 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
32dd0 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
32de0 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
32df0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
32e00 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
32e10 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
32e20 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
32e30 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
32e40 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
32e50 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
32e60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
32e70 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
32e80 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
32e90 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
32ea0 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
32eb0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
32ec0 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
32ed0 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
32ee0 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
32ef0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
32f00 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
32f10 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
32f20 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
32f30 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
32f40 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
32f50 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
32f60 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
32f70 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
32f80 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
32f90 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
32fa0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
32fb0 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
32fc0 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
32fd0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
32fe0 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
32ff0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
33000 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
33010 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
33020 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
33030 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
33040 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33050 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
33060 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
33070 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
33080 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
33090 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
330a0 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
330b0 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
330c0 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
330d0 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
330e0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
330f0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
33100 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
33110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
33120 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
33130 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
33140 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
33150 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
33160 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
33170 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
33180 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
33190 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
331a0 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
331b0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
331c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
331d0 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
331e0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
331f0 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
33200 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
33210 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
33220 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
33230 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
33240 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
33250 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
33260 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
33270 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
33280 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
33290 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
332a0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
332b0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
332c0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
332d0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
332e0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
332f0 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
33300 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
33310 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
33320 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
33330 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
33340 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
33350 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
33360 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
33370 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
33380 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
33390 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
333a0 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
333b0 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
333c0 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
333d0 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
333e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
333f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
33400 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
33410 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
33420 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
33430 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
33440 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
33450 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
33460 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
33470 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
33480 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
33490 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
334a0 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
334b0 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
334c0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
334d0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
334e0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
334f0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
33500 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
33510 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
33520 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
33530 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
33540 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
33550 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
33560 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
33570 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33580 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
33590 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
335a0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
335b0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
335c0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
335d0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
335e0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
335f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33600 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
33610 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
33620 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
33630 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
33640 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
33650 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
33660 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
33670 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
33680 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
33690 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
336a0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
336b0 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
336c0 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
336d0 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
336e0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
336f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33700 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
33710 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
33720 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
33730 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
33740 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
33750 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
33760 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
33770 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
33780 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
33790 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
337a0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
337b0 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
337c0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
337d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
337e0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
337f0 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
33800 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
33810 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
33820 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
33830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33840 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
33850 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
33860 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
33870 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
33880 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
33890 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
338a0 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
338b0 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
338c0 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
338d0 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
338e0 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
338f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
33900 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
33910 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
33920 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
33930 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
33940 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
33950 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
33960 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
33970 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
33980 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
33990 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
339a0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
339b0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
339c0 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
339d0 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
339e0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
339f0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
33a00 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
33a10 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
33a20 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
33a30 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
33a40 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
33a50 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
33a60 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
33a70 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
33a80 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
33a90 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
33aa0 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
33ab0 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
33ac0 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
33ad0 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
33ae0 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
33af0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
33b00 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
33b10 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
33b20 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
33b30 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
33b40 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
33b50 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
33b60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
33b70 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
33b80 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
33b90 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
33ba0 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
33bb0 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
33bc0 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
33bd0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
33be0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
33bf0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
33c00 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
33c10 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
33c20 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
33c30 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
33c40 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
33c50 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
33c60 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
33c70 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
33c80 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
33c90 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
33ca0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
33cb0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
33cc0 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
33cd0 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
33ce0 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
33cf0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
33d00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
33d10 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
33d20 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
33d30 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
33d40 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
33d50 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
33d60 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
33d70 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
33d80 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
33d90 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
33da0 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
33db0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
33dc0 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
33dd0 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
33de0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
33df0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
33e00 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
33e10 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
33e20 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
33e30 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
33e40 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
33e50 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
33e60 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
33e70 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
33e80 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
33e90 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
33ea0 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
33eb0 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
33ec0 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
33ed0 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
33ee0 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
33ef0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
33f00 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
33f10 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
33f20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
33f30 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
33f40 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
33f50 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
33f60 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
33f70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33f80 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
33f90 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
33fa0 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
33fb0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
33fc0 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
33fd0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
33fe0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
33ff0 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
34000 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
34010 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
34020 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
34030 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
34040 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
34050 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
34060 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
34070 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
34080 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
34090 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
340a0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
340b0 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
340c0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
340d0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
340e0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
340f0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
34100 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
34110 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
34120 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
34130 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
34140 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
34150 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
34160 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
34170 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
34180 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
34190 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
341a0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
341b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
341c0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
341d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
341e0 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
341f0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
34200 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
34210 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
34220 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
34230 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
34240 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
34250 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
34260 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
34270 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
34280 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
34290 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
342a0 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
342b0 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
342c0 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
342d0 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
342e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
342f0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
34300 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
34310 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
34320 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
34330 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
34340 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
34350 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
34360 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
34370 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
34380 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
34390 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
343a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
343b0 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
343c0 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73  le.**.** ^Closes
343d0 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
343e0 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  andle]..**.** ^C
343f0 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
34400 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
34410 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
34420 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
34430 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
34440 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
34450 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
34460 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
34470 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34480 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
34490 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
344a0 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77  e]..** ^If any w
344b0 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20  rites were made 
344c0 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65  to the BLOB, the
344d0 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20  y might be held 
344e0 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69  in cache.** unti
344f0 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72  l the close oper
34500 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69  ation if they wi
34510 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ll fit..**.** ^(
34520 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
34530 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
34540 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
34550 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
34560 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
34570 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
34580 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
34590 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
345a0 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
345b0 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
345c0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
345d0 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
345e0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
345f0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
34600 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a  rn value.)^.**.*
34610 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20  * ^(The BLOB is 
34620 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
34630 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
34640 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34650 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
34660 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
34670 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
34680 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  .)^.**.** ^Calli
34690 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
346a0 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  with a null poin
346b0 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f 75  ter (such as wou
346c0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a  ld be returned.*
346d0 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63 61  * by a failed ca
346e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
346f0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20  lob_open()]) is 
34700 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
34710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34720 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
34730 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
34740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
34750 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
34760 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
34770 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65  .** ^Returns the
34780 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
34790 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73  f the BLOB acces
347a0 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a  sible via the .*
347b0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  * successfully o
347c0 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pened [BLOB hand
347d0 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
347e0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a  argument.  ^The.
347f0 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62  ** incremental b
34800 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73  lob I/O routines
34810 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f   can only read o
34820 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78  r overwriting ex
34830 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63  isting.** blob c
34840 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e  ontent; they can
34850 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73  not change the s
34860 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a  ize of a blob..*
34870 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34880 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
34890 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
348a0 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
348b0 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
348c0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
348d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
348e0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
348f0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
34900 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
34910 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
34920 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
34930 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
34940 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
34950 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
34960 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34970 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
34980 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
34990 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
349a0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
349b0 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
349c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
349d0 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
349e0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
349f0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ly.**.** ^(This 
34a00 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
34a10 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
34a20 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  om an open [BLOB
34a30 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a   handle] into a.
34a40 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
34a50 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74  ed buffer. N byt
34a60 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
34a70 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65  opied into buffe
34a80 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  r Z.** from the 
34a90 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
34aa0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
34ab0 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ffset.)^.**.** ^
34ac0 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
34ad0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
34ae0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
34af0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
34b00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
34b10 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
34b20 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
34b30 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f  ad.  ^If N or iO
34b40 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
34b50 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
34b60 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
34b70 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
34b80 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e  ta is read..** ^
34b90 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
34ba0 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
34bb0 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
34bc0 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
34bd0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
34be0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
34bf0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
34c00 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
34c10 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
34c20 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
34c30 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
34c40 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
34c50 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
34c60 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
34c70 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ABORT]..**.** ^(
34c80 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
34c90 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20  te3_blob_read() 
34ca0 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
34cb0 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
34cc0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
34cd0 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34ce0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34cf0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
34d00 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
34d10 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34d20 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
34d30 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
34d40 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
34d50 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34d60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34d70 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34d80 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34d90 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34da0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34db0 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
34dc0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
34dd0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
34de0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34df0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34e00 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
34e10 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34e20 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
34e30 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
34e40 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ite()]..*/.int s
34e50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
34e60 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
34e70 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
34e80 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
34e90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34ea0 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
34eb0 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
34ec0 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ally.**.** ^This
34ed0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
34ee0 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
34ef0 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  into an open [BL
34f00 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20  OB handle] from 
34f10 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
34f20 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20  lied buffer. ^N 
34f30 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34f40 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
34f50 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
34f60 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
34f70 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
34f80 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
34f90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f  .** ^If the [BLO
34fa0 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
34fb0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
34fc0 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
34fd0 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
34fe0 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
34ff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
35000 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
35010 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
35020 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
35030 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
35040 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
35050 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  ^This function m
35060 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
35070 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
35080 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
35090 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
350a0 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
350b0 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
350c0 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
350d0 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
350e0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
350f0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
35100 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
35110 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
35120 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
35130 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
35140 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20  written.  ^If N 
35150 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
35160 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
35170 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
35180 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
35190 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ritten..** The s
351a0 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
351b0 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d  (and hence the m
351c0 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
351d0 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61  N+iOffset).** ca
351e0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
351f0 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
35200 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
35210 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
35220 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f  * ^An attempt to
35230 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70   write to an exp
35240 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
35250 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
35260 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
35270 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
35280 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68  .  ^Writes to th
35290 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
352a0 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
352b0 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
352c0 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
352d0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
352e0 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
352f0 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
35300 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
35310 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
35320 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
35330 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
35340 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
35350 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
35360 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
35370 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
35380 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
35390 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  ts..**.** ^(On s
353a0 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f  uccess, sqlite3_
353b0 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74  blob_write() ret
353c0 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
353d0 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
353e0 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f    [error code] o
353f0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
35400 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
35410 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
35420 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
35430 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
35440 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
35450 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
35460 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
35470 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
35480 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
35490 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
354a0 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
354b0 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
354c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
354d0 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
354e0 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
354f0 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
35500 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
35510 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
35520 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
35530 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
35540 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
35550 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
35560 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
35570 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
35580 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
35590 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
355a0 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
355b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
355c0 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65  EF: Virtual File
355d0 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
355e0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
355f0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
35600 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
35610 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
35620 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
35630 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
35640 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
35650 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
35660 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74  tem.  Most SQLit
35670 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  e builds come wi
35680 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
35690 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
356a0 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
356b0 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
356c0 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
356d0 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
356e0 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
356f0 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
35700 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
35710 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
35720 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
35730 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  vided..**.** ^Th
35740 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
35750 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
35760 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35770 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20   to a VFS given 
35780 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61  its name..** ^Na
35790 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
357a0 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  sitive..** ^Name
357b0 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
357c0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
357d0 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72  ngs..** ^If ther
357e0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
357f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
35800 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
35810 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
35820 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
35830 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
35840 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20  ned..**.** ^New 
35850 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
35860 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
35870 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
35880 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56  ..** ^Each new V
35890 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64  FS becomes the d
358a0 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68  efault VFS if th
358b0 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
358c0 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  is set..** ^The 
358d0 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
358e0 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
358f0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
35900 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f  t injury..** ^To
35910 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
35920 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
35930 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
35940 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
35950 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
35960 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
35970 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
35980 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
35990 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
359a0 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
359b0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
359c0 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
359d0 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
359e0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
359f0 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
35a00 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
35a10 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35a20 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
35a30 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74  .**.** ^Unregist
35a40 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
35a50 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
35a60 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
35a70 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68  face..** ^(If th
35a80 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
35a90 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
35aa0 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
35ab0 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
35ac0 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
35ad0 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
35ae0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
35af0 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  .)^.*/.sqlite3_v
35b00 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f  fs *sqlite3_vfs_
35b10 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20  find(const char 
35b20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20  *zVfsName);.int 
35b30 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
35b40 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
35b50 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29  *, int makeDflt)
35b60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
35b70 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c  s_unregister(sql
35b80 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a  ite3_vfs*);../*.
35b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
35ba0 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  exes.**.** The S
35bb0 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
35bc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  these routines f
35bd0 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e  or thread.** syn
35be0 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68  chronization. Th
35bf0 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
35c00 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
35c10 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
35c20 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
35c30 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
35c40 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
35c50 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
35c60 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
35c70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
35c80 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
35c90 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
35ca0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35cb0 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75  s.** of these mu
35cc0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
35cd0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
35ce0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
35cf0 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
35d00 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
35d10 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68  pile-time.  ^(Th
35d20 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69  e following.** i
35d30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61  mplementations a
35d40 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  re available in 
35d50 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a  the SQLite core:
35d60 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
35d70 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
35d80 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_OS2.** <li>  
35d90 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
35da0 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20  HREAD.** <li>   
35db0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
35dc0 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
35dd0 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
35de0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  </ul>)^.**.** ^T
35df0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
35e00 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
35e10 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
35e20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
35e30 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
35e40 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
35e50 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
35e60 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
35e70 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
35e80 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49  tion.  ^The SQLI
35e90 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
35ea0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
35eb0 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
35ec0 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
35ed0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
35ee0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
35ef0 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
35f00 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
35f10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  s..**.** ^(If SQ
35f20 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
35f30 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
35f40 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72  _MUTEX_APPDEF pr
35f50 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61  eprocessor.** ma
35f60 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74  cro defined (wit
35f70 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45  h "-DSQLITE_MUTE
35f80 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68  X_APPDEF=1"), th
35f90 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69  en no mutex.** i
35fa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35fb0 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74   included with t
35fc0 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74  he library. In t
35fd0 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  his case the.** 
35fe0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
35ff0 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d   supply a custom
36000 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
36010 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a  ation using the.
36020 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
36030 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20  G_MUTEX] option 
36040 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
36050 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e  onfig() function
36060 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  .** before calli
36070 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ng sqlite3_initi
36080 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f  alize() or any o
36090 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69  ther public sqli
360a0 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  te3_.** function
360b0 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69   that calls sqli
360c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
360d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
360e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
360f0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c  oc() routine all
36100 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20  ocates a new.** 
36110 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e  mutex and return
36120 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
36130 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e  t. ^If it return
36140 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
36150 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
36160 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
36170 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69  llocated.  ^SQLi
36180 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
36190 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
361a0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
361b0 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
361c0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  .** to sqlite3_m
361d0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20  utex_alloc() is 
361e0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
361f0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a  eger constants:.
36200 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
36210 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36220 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _FAST.** <li>  S
36230 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36240 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  RSIVE.** <li>  S
36250 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
36260 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69  IC_MASTER.** <li
36270 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36280 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c  STATIC_MEM.** <l
36290 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
362a0 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20  _STATIC_MEM2.** 
362b0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
362c0 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a  EX_STATIC_PRNG.*
362d0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
362e0 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a  UTEX_STATIC_LRU.
362f0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
36300 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
36310 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  2.** </ul>)^.**.
36320 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 77  ** ^The first tw
36330 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c  o constants (SQL
36340 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
36350 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36360 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61  RECURSIVE).** ca
36370 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
36380 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
36390 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
363a0 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75  ex.  ^The new mu
363b0 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
363c0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
363d0 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
363e0 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
363f0 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
36400 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
36410 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a  _FAST is used..*
36420 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
36430 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
36440 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
36450 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
36460 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
36470 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36480 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
36490 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
364a0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
364b0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
364c0 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72  only request a r
364d0 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69  ecursive mutex i
364e0 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65  n.** cases where
364f0 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73   it really needs
36500 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73   one.  ^If a fas
36510 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76  ter non-recursiv
36520 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  e mutex.** imple
36530 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61  mentation is ava
36540 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f  ilable on the ho
36550 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65  st platform, the
36560 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d   mutex subsystem
36570 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e  .** might return
36580 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e   such a mutex in
36590 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c   response to SQL
365a0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a  ITE_MUTEX_FAST..
365b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72  **.** ^The other
365c0 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74   allowed paramet
365d0 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ers to sqlite3_m
365e0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e  utex_alloc() (an
365f0 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20  ything other.** 
36600 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  than SQLITE_MUTE
36610 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
36620 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36630 45 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a  E) each return.*
36640 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
36650 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74   static preexist
36660 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78  ing mutex.  ^Six
36670 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
36680 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74  are.** used by t
36690 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  he current versi
366a0 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46  on of SQLite.  F
366b0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
366c0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20  f SQLite.** may 
366d0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  add additional s
366e0 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20  tatic mutexes.  
366f0 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  Static mutexes a
36700 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  re for internal.
36710 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
36720 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
36730 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51  ions that use SQ
36740 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f  Lite mutexes sho
36750 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20  uld.** use only 
36760 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
36770 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  xes returned by 
36780 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
36790 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  T or.** SQLITE_M
367a0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a  UTEX_RECURSIVE..
367b0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
367c0 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
367d0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
367e0 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
367f0 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
36800 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
36810 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
36820 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
36830 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
36840 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
36850 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
36860 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f  y call.  ^But fo
36870 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20  r the static.** 
36880 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
36890 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
368a0 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
368b0 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
368c0 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
368d0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
368e0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
368f0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
36900 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
36910 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
36920 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
36930 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73  tex.  ^SQLite is
36940 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c   careful to deal
36950 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20  locate every.** 
36960 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68  dynamic mutex th
36970 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e  at it allocates.
36980 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75    The dynamic mu
36990 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62  texes must not b
369a0 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e  e in.** use when
369b0 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
369c0 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69  cated.  Attempti
369d0 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ng to deallocate
369e0 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74   a static.** mut
369f0 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ex results in un
36a00 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
36a10 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72  .  ^SQLite never
36a20 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
36a30 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  a static mutex..
36a40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36a50 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36a60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
36a70 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
36a80 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
36a90 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
36aa0 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65  ^If another thre
36ab0 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
36ac0 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
36ad0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
36ae0 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
36af0 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
36b00 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
36b10 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
36b20 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71  E_BUSY.  ^The sq
36b30 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36b40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36b50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a  rns [SQLITE_OK].
36b60 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66  ** upon successf
36b70 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74  ul entry.  ^(Mut
36b80 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
36b90 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
36ba0 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
36bb0 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
36bc0 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
36bd0 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
36be0 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20  * In such cases 
36bf0 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75  the,.** mutex mu
36c00 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20  st be exited an 
36c10 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  equal number of 
36c20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f  times before ano
36c30 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63  ther thread.** c
36c40 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49  an enter.)^  ^(I
36c50 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  f the same threa
36c60 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72  d tries to enter
36c70 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69   any other.** ki
36c80 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65  nd of mutex more
36c90 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20   than once, the 
36ca0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
36cb0 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  fined..** SQLite
36cc0 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
36cd0 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
36ce0 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
36cf0 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29  use of mutexes.)
36d00 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73  ^.**.** ^(Some s
36d10 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d  ystems (for exam
36d20 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29  ple, Windows 95)
36d30 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
36d40 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
36d50 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
36d60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36d70 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73  y().  On those s
36d80 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f  ystems, sqlite3_
36d90 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77  mutex_try().** w
36da0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
36db0 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
36dc0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
36dd0 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a  only ever uses.*
36de0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
36df0 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69  try() as an opti
36e00 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73  mization so this
36e10 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62   is acceptable b
36e20 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a  ehavior.)^.**.**
36e30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
36e40 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74  tex_leave() rout
36e50 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65  ine exits a mute
36e60 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72  x that was.** pr
36e70 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64  eviously entered
36e80 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
36e90 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68  ead.   ^(The beh
36ea0 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
36eb0 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74  fined if the mut
36ec0 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  ex is not curren
36ed0 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  tly entered by t
36ee0 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68  he.** calling th
36ef0 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63  read or is not c
36f00 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
36f10 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  ed.  SQLite will
36f20 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
36f30 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  her.)^.**.** ^If
36f40 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
36f50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
36f60 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f  nter(), sqlite3_
36f70 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a  mutex_try(), or.
36f80 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
36f90 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55  _leave() is a NU
36fa0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
36fb0 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69   all three routi
36fc0 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73  nes.** behave as
36fd0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53   no-ops..**.** S
36fe0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
36ff0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
37000 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
37010 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
37020 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
37030 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
37040 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
37050 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37060 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
37070 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37080 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
37090 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
370a0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
370b0 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
370c0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
370d0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
370e0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
370f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37100 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62  Mutex Methods Ob
37110 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
37120 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
37130 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73  tructure defines
37140 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72   the low-level r
37150 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20  outines.** used 
37160 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20  to allocate and 
37170 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a  use mutexes..**.
37180 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20  ** Usually, the 
37190 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d  default mutex im
371a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72  plementations pr
371b0 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65  ovided by SQLite
371c0 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65   are.** sufficie
371d0 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  nt, however the 
371e0 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74  user has the opt
371f0 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74  ion of substitut
37200 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20  ing a custom.** 
37210 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
37220 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64  or specialized d
37230 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79  eployments or sy
37240 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20  stems for which 
37250 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
37260 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69  ot provide a sui
37270 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
37280 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61  tion. In this ca
37290 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20  se, the user.** 
372a0 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75  creates and popu
372b0 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lates an instanc
372c0 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
372d0 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74  ure to pass.** t
372e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
372f0 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68  () along with th
37300 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
37310 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  _MUTEX] option..
37320 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  ** Additionally,
37330 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
37340 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  this structure c
37350 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e  an be used as an
37360 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61  .** output varia
37370 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e  ble when queryin
37380 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72  g the system for
37390 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74   the current mut
373a0 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
373b0 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20  tion, using the 
373c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
373d0 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  ETMUTEX] option.
373e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
373f0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
37400 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
37410 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
37420 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
37430 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
37440 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
37450 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
37460 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
37470 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20  ^The xMutexInit 
37480 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
37490 20 62 79 20 53 51 4c 69 74 65 20 65 78 61 63 74   by SQLite exact
374a0 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
374b0 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61  .** effective ca
374c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69  ll to [sqlite3_i
374d0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  nitialize()]..**
374e0 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45  .** ^The xMutexE
374f0 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65  nd method define
37500 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
37510 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ure is invoked a
37520 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73  s.** part of sys
37530 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20  tem shutdown by 
37540 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  the sqlite3_shut
37550 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e  down() function.
37560 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   The.** implemen
37570 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  tation of this m
37580 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65  ethod is expecte
37590 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c  d to release all
375a0 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20   outstanding.** 
375b0 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e  resources obtain
375c0 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20  ed by the mutex 
375d0 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e  methods implemen
375e0 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c  tation, especial
375f0 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61  ly.** those obta
37600 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74  ined by the xMut
37610 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20  exInit method.  
37620 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29  ^The xMutexEnd()
37630 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
37640 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
37650 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
37660 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37670 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
37680 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69  ** ^(The remaini
37690 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73  ng seven methods
376a0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
376b0 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74   structure (xMut
376c0 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74  exAlloc,.** xMut
376d0 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e  exFree, xMutexEn
376e0 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20  ter, xMutexTry, 
376f0 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75  xMutexLeave, xMu
37700 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78  texHeld and.** x
37710 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d  MutexNotheld) im
37720 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c  plement the foll
37730 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
37740 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a   (respectively):
37750 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
37760 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37770 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c  mutex_alloc()] <
37780 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
37790 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66  [sqlite3_mutex_f
377a0 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ree()] </li>.** 
377b0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
377c0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20  _mutex_enter()] 
377d0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
377e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
377f0 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  try()] </li>.** 
37800 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
37810 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20  _mutex_leave()] 
37820 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
37830 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37840 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
37850 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37860 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
37870 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  )] </li>.** </ul
37880 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e  >)^.**.** The on
37890 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ly difference is
378a0 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63   that the public
378b0 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e   sqlite3_XXX fun
378c0 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65  ctions enumerate
378d0 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e  d.** above silen
378e0 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69  tly ignore any i
378f0 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20  nvocations that 
37900 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  pass a NULL poin
37910 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
37920 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
37930 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c  handle. The impl
37940 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
37950 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  he methods defin
37960 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74  ed.** by this st
37970 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20  ructure are not 
37980 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64  required to hand
37990 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68  le this case, th
379a0 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20  e results.** of 
379b0 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  passing a NULL p
379c0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
379d0 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
379e0 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66  handle are undef
379f0 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74  ined.** (i.e. it
37a00 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74   is acceptable t
37a10 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
37a20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
37a30 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a   segfaults if.**
37a40 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
37a50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a  NULL pointer)..*
37a60 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49  *.** The xMutexI
37a70 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73  nit() method mus
37a80 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
37a90 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61    ^It must be ha
37aa0 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76  rmless to.** inv
37ab0 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29  oke xMutexInit()
37ac0 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77   mutiple times w
37ad0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
37ae0 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f  rocess and witho
37af0 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e  ut.** intervenin
37b00 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65  g calls to xMute
37b10 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20  xEnd().  Second 
37b20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
37b30 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65  alls to.** xMute
37b40 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20  xInit() must be 
37b50 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78  no-ops..**.** ^x
37b60 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
37b70 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
37b80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37b90 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  n ([sqlite3_mall
37ba0 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73  oc()].** and its
37bb0 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e   associates).  ^
37bc0 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65  Similarly, xMute
37bd0 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f  xAlloc() must no
37be0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d  t use SQLite mem
37bf0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
37c00 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d  n for a static m
37c10 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20  utex.  ^However 
37c20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61  xMutexAlloc() ma
37c30 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20  y use SQLite.** 
37c40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37c50 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20  n for a fast or 
37c60 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e  recursive mutex.
37c70 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
37c80 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78  ill invoke the x
37c90 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f  MutexEnd() metho
37ca0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
37cb0 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a  shutdown()] is.*
37cc0 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e  * called, but on
37cd0 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20  ly if the prior 
37ce0 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e  call to xMutexIn
37cf0 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  it returned SQLI
37d00 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75  TE_OK..** If xMu
37d10 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e  texInit fails in
37d20 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20   any way, it is 
37d30 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61  expected to clea
37d40 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c  n up after itsel
37d50 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65  f.** prior to re
37d60 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65  turning..*/.type
37d70 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
37d80 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
37d90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37da0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
37db0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
37dc0 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78  hods {.  int (*x
37dd0 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29  MutexInit)(void)
37de0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37df0 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71  End)(void);.  sq
37e00 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78  lite3_mutex *(*x
37e10 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29  MutexAlloc)(int)
37e20 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
37e30 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d  xFree)(sqlite3_m
37e40 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
37e50 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73  (*xMutexEnter)(s
37e60 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37e70 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54  .  int (*xMutexT
37e80 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ry)(sqlite3_mute
37e90 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
37ea0 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69  MutexLeave)(sqli
37eb0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
37ec0 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64  int (*xMutexHeld
37ed0 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37ee0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37ef0 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74  exNotheld)(sqlit
37f00 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a  e3_mutex *);.};.
37f10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37f20 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74   Mutex Verificat
37f30 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
37f40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
37f50 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20  utex_held() and 
37f60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
37f70 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73  theld() routines
37f80 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64  .** are intended
37f90 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
37fa0 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
37fb0 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74  nts.  ^The SQLit
37fc0 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20  e core.** never 
37fd0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
37fe0 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64  nes except insid
37ff0 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e  e an assert() an
38000 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  d applications.*
38010 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f  * are advised to
38020 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64   follow the lead
38030 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e   of the core.  ^
38040 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
38050 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
38060 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
38070 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
38080 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
38090 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
380a0 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
380b0 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61   flag.  ^Externa
380c0 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  l mutex implemen
380d0 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f  tations.** are o
380e0 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20  nly required to 
380f0 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f  provide these ro
38100 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45  utines if SQLITE
38110 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66  _DEBUG is.** def
38120 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42  ined and if NDEB
38130 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65  UG is not define
38140 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
38150 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
38160 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
38170 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
38180 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
38190 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
381a0 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
381b0 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
381c0 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  thread..**.** ^T
381d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
381e0 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
381f0 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65  d to provided ve
38200 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a  rsions of these.
38210 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
38220 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20   actually work. 
38230 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  If the implement
38240 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70  ation does not p
38250 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a  rovide working.*
38260 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  * versions of th
38270 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74  ese routines, it
38280 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74   should at least
38290 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74   provide stubs t
382a0 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65  hat always.** re
382b0 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61  turn true so tha
382c0 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67  t one does not g
382d0 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65  et spurious asse
382e0 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a  rtion failures..
382f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
38300 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
38310 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
38320 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38330 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
38340 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
38350 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73 65 65  rn 1.   This see
38360 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  ms counter-intui
38370 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c  tive since.** cl
38380 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20  early the mutex 
38390 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69  cannot be held i
383a0 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  f it does not ex
383b0 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a  ist.  But the.**
383c0 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20   the reason the 
383d0 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65  mutex does not e
383e0 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20  xist is because 
383f0 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74  the build is not
38400 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65  .** using mutexe
38410 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f  s.  And we do no
38420 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72  t want the asser
38430 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  t() containing t
38440 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  he.** call to sq
38450 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
38460 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61  () to fail, so a
38470 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
38480 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f   is.** the appro
38490 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20  priate thing to 
384a0 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  do.  ^The sqlite
384b0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
384c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
384d0 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
384e0 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
384f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
38500 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47  /.#ifndef NDEBUG
38510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
38520 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  ex_held(sqlite3_
38530 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
38540 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
38550 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
38560 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  *);.#endif../*.*
38570 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
38580 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68  x Types.**.** Th
38590 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
385a0 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
385b0 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
385c0 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
385d0 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
385e0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
385f0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  stants..**.** Th
38600 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 20  e set of static 
38610 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e  mutexes may chan
38620 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69  ge from one SQLi
38630 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  te release to th
38640 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
38650 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ications that ov
38660 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c 74  erride the built
38670 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20  -in mutex logic 
38680 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61  must be.** prepa
38690 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61  red to accommoda
386a0 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  te additional st
386b0 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f  atic mutexes..*/
386c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
386d0 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20  MUTEX_FAST      
386e0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
386f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
38700 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31  CURSIVE        1
38710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38720 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
38730 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65  TER    2.#define
38740 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38750 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33  ATIC_MEM       3
38760 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c    /* sqlite3_mal
38770 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  loc() */.#define
38780 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38790 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34  ATIC_MEM2      4
387a0 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f    /* NOT USED */
387b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
387c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45  MUTEX_STATIC_OPE
387d0 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c  N      4  /* sql
387e0 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20  ite3BtreeOpen() 
387f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38800 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50  E_MUTEX_STATIC_P
38810 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73  RNG      5  /* s
38820 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20  qlite3_random() 
38830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38840 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
38850 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c  RU       6  /* l
38860 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a  ru page list */.
38870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
38880 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32  UTEX_STATIC_LRU2
38890 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20        7  /* lru 
388a0 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  page list */../*
388b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
388c0 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65 78  trieve the mutex
388d0 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
388e0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  connection.**.**
388f0 20 5e 54 68 69 73 20 69 6e 74 65 72 66