/ Hex Artifact Content
Login

Artifact 96b0bed7825da354119a9742a83033087c537133:


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 2c 20 63 68 61 72 20 2a 2a 29 3b 0a 20 20 69  e, char **);.  i
9690: 6e 74 20 28 2a 78 53 68 6d 50 75 73 68 29 28 73  nt (*xShmPush)(s
96a0: 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a 20 20  qlite3_shm*);.  
96b0: 69 6e 74 20 28 2a 78 53 68 6d 50 75 6c 6c 29 28  int (*xShmPull)(
96c0: 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a 20  sqlite3_shm*);. 
96d0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
96e0: 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c 20 69  (sqlite3_shm*, i
96f0: 6e 74 20 6c 6f 63 6b 54 79 70 65 2c 20 69 6e 74  nt lockType, int
9700: 20 6f 66 73 74 2c 20 69 6e 74 20 6e 42 79 74 65   ofst, int nByte
9710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43  );.  int (*xShmC
9720: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 73 68  lose)(sqlite3_sh
9730: 6d 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  m*);.  int (*xSh
9740: 6d 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  mDelete)(sqlite3
9750: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9760: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 69 6e 74  r *zName);.  int
9770: 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
9780: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9790: 63 68 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73  char *zOld, cons
97a0: 74 20 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69 6e  t char *zNew, in
97b0: 74 20 64 69 72 53 79 6e 63 29 3b 0a 20 20 69 6e  t dirSync);.  in
97c0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
97d0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
97e0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
97f0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9800: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
9810: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
9820: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
9830: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9840: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
9850: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9860: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
9870: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
9880: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
9890: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
98a0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
98b0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
98c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
98d0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
98e0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
98f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
9900: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
9910: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
9920: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
9930: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
9940: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
9950: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
9960: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
9970: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
9980: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
9990: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
99a0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
99b0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
99c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
99d0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
99e0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
99f0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
9a00: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
9a10: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
9a20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9a30: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
9a40: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9a50: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9a60: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
9a70: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
9a80: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9a90: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
9aa0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9ab0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
9ac0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
9ad0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
9ae0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9af0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
9b00: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9b10: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
9b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
9b30: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
9b40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9b50: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
9b60: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
9b70: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
9b80: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
9b90: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
9ba0: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
9bb0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
9bc0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
9bd0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
9be0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
9bf0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
9c00: 65 20 73 70 65 63 69 66 69 63 20 6c 6f 63 6b 69  e specific locki
9c10: 6e 67 20 61 63 74 69 6f 6e 2e 20 20 45 78 61 63  ng action.  Exac
9c20: 74 6c 79 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  tly one of the f
9c30: 69 72 73 74 20 74 68 72 65 65 0a 2a 2a 20 76 61  irst three.** va
9c40: 6c 75 65 73 20 6d 75 73 74 20 62 65 20 75 73 65  lues must be use
9c50: 64 20 69 6e 69 20 74 68 65 20 6c 6f 63 6b 54 79  d ini the lockTy
9c60: 70 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  pe parameter.  T
9c70: 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 76 61 6c  he fourth.** val
9c80: 75 65 20 28 53 51 4c 49 54 45 5f 53 48 4d 5f 42  ue (SQLITE_SHM_B
9c90: 4c 4f 43 4b 29 20 63 61 6e 20 6f 70 74 69 6f 6e  LOCK) can option
9ca0: 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 69 6e 74  ally be ORed int
9cb0: 6f 20 74 68 65 20 6c 6f 63 6b 54 79 70 65 0a 2a  o the lockType.*
9cc0: 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 63  * parameter to c
9cd0: 61 75 73 65 20 74 68 65 20 74 68 72 65 61 64 20  ause the thread 
9ce0: 74 6f 20 62 6c 6f 63 6b 20 75 6e 74 69 6c 20 74  to block until t
9cf0: 68 65 20 6c 6f 63 6b 20 62 65 63 6f 6d 65 73 0a  he lock becomes.
9d00: 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f  ** available..*/
9d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d20: 53 48 4d 5f 52 44 4c 4b 20 20 20 30 78 30 31 0a  SHM_RDLK   0x01.
9d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9d40: 48 4d 5f 57 52 4c 4b 20 20 20 30 78 30 32 0a 23  HM_WRLK   0x02.#
9d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9d60: 4d 5f 55 4e 4c 4b 20 20 20 30 78 30 34 0a 23 64  M_UNLK   0x04.#d
9d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
9d80: 5f 42 4c 4f 43 4b 20 20 30 78 30 38 0a 0a 2f 2a  _BLOCK  0x08../*
9d90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
9da0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
9db0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
9dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
9dd0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
9de0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
9df0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
9e00: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
9e10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
9e20: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
9e30: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
9e40: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
9e50: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
9e60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9e70: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
9e80: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
9e90: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
9ea0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
9eb0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
9ec0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
9ed0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
9ee0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
9ef0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
9f00: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
9f10: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
9f20: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
9f30: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
9f40: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
9f50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
9f60: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
9f70: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
9f80: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
9f90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9fa0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
9fb0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
9fc0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
9fd0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
9fe0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
9ff0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
a000: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
a010: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
a020: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
a030: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
a040: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
a050: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
a060: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a070: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
a080: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
a090: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
a0a0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
a0b0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
a0c0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
a0d0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
a0e0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
a0f0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
a100: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
a110: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a120: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
a130: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a140: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
a150: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
a160: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
a170: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
a180: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
a190: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
a1a0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
a1b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a1c0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
a1d0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
a1e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
a1f0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
a200: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
a210: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
a220: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
a230: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
a240: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
a250: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
a260: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
a270: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
a280: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
a290: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a2a0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
a2b0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
a2c0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
a2d0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
a2e0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
a2f0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
a300: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a310: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
a320: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
a330: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a340: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
a350: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
a360: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
a370: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
a380: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
a390: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
a3a0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
a3b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a3c0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
a3d0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a3e0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
a3f0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
a400: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
a410: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
a420: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
a430: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
a440: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
a450: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
a460: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
a470: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
a480: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
a490: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
a4a0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
a4b0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
a4c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
a4d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
a4e0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
a4f0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
a500: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
a510: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
a520: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
a530: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
a540: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
a550: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
a560: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
a570: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
a580: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
a590: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
a5a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a5b0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
a5c0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
a5d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
a5e0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
a5f0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
a600: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
a610: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
a620: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
a630: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
a640: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
a650: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
a660: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
a670: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
a680: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
a690: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
a6a0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
a6b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a6c0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a6d0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a6e0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a6f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a700: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a710: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a720: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a730: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a740: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a750: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a760: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a770: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a780: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a790: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a7a0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a7b0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a7c0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a7d0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a7e0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a7f0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a800: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a810: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a820: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a830: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a840: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
a850: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
a860: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
a870: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a880: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a890: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a8a0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a8b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a8c0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a8d0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a8e0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a8f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a900: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a910: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a920: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a930: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a940: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a950: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a960: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a970: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a980: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a990: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a9a0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a9b0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a9c0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a9d0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a9e0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a9f0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
aa00: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
aa10: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
aa20: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
aa30: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
aa40: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
aa50: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
aa60: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
aa70: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
aa80: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
aa90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
aaa0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
aab0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
aac0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
aad0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
aae0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
aaf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
ab00: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
ab10: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
ab20: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
ab30: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
ab40: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
ab50: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
ab60: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
ab70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ab80: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
ab90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
aba0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
abb0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
abc0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
abd0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
abe0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
abf0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ac00: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
ac10: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
ac20: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
ac30: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
ac40: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
ac50: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
ac60: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
ac70: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
ac80: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
ac90: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
aca0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
acb0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
acc0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
acd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
ace0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
acf0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
ad00: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
ad10: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
ad20: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
ad30: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
ad40: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
ad50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ad60: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
ad70: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ad80: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
ad90: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
ada0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
adb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
adc0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
add0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
ade0: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
adf0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
ae00: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
ae10: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
ae20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
ae30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
ae40: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
ae50: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
ae60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
ae70: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
ae80: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
ae90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
aea0: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
aeb0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
aec0: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
aed0: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
aee0: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
aef0: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
af00: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
af10: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
af20: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
af30: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
af40: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
af50: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
af60: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
af70: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
af80: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
af90: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
afa0: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
afb0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
afc0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
afd0: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
afe0: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
aff0: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
b000: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
b010: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
b020: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
b030: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
b040: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
b050: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
b060: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
b070: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
b080: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
b090: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
b0a0: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
b0b0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
b0c0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
b0d0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
b0e0: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
b0f0: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
b100: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
b110: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b120: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
b130: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
b140: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
b150: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
b160: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
b170: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
b180: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
b190: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
b1a0: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
b1b0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
b1c0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
b1d0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
b1e0: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
b1f0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
b200: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b210: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
b220: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
b230: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b240: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
b250: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
b260: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
b270: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b280: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
b290: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
b2a0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
b2b0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
b2c0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
b2d0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
b2e0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
b2f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
b300: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
b310: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
b320: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
b330: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
b340: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
b350: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b360: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
b370: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
b380: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b390: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
b3a0: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
b3b0: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
b3c0: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
b3d0: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
b3e0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
b3f0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
b400: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
b410: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
b420: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
b430: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b440: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
b450: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b460: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
b470: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
b480: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
b490: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
b4a0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
b4b0: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
b4c0: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
b4d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
b4e0: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
b4f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
b500: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
b510: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
b520: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
b530: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
b540: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
b550: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
b560: 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  t).  The.** sqli
b570: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
b580: 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
b590: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d   only be used im
b5a0: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a  mediately after.
b5b0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
b5c0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72  connection is cr
b5d0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
b5e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a  ite3_open()],.**
b5f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
b600: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
b610: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a  _open_v2()].  .*
b620: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
b630: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
b640: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
b650: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
b660: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
b670: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65  verb - an intege
b680: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69  r code that indi
b690: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73  cates what.** as
b6a0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
b6b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b6c0: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
b6d0: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e  gured..** The on
b6e0: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  ly choice for th
b6f0: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c  is value is [SQL
b700: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
b710: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20  KASIDE]..** New 
b720: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79  verbs are likely
b730: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20   to be added in 
b740: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
b750: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64  of SQLite..** Ad
b760: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
b770: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65  ts depend on the
b780: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
b790: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
b7a0: 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
b7b0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
b7c0: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
b7d0: 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
b7e0: 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
b7f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
b800: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
b810: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
b820: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
b830: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
b840: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
b850: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
b860: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
b870: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
b880: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
b890: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
b8a0: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
b8b0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
b8c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
b8d0: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
b8e0: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
b8f0: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
b900: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
b910: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
b920: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
b930: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b940: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
b950: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
b960: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
b970: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
b980: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b990: 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
b9a0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
b9b0: 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
b9c0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
b9d0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
b9e0: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
b9f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ba00: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
ba10: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
ba20: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
ba30: 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
ba40: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
ba50: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
ba60: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
ba70: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
ba80: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
ba90: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
baa0: 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
bab0: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
bac0: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
bad0: 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
bae0: 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
baf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
bb00: 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
bb10: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
bb20: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
bb30: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
bb40: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
bb50: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
bb60: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
bb70: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
bb80: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
bb90: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
bba0: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
bbb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
bbc0: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
bbd0: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
bbe0: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
bbf0: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
bc00: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
bc10: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
bc20: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
bc30: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
bc40: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
bc50: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
bc60: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
bc70: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
bc80: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
bc90: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
bca0: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
bcb0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
bcc0: 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65  xMalloc and xFre
bcd0: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
bce0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
bcf0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
bd00: 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
bd10: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
bd20: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
bd30: 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  e xRealloc metho
bd40: 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  d must work like
bd50: 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20   realloc() from 
bd60: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
bd70: 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74  ibrary.** with t
bd80: 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61  he exception tha
bd90: 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t if the second 
bda0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61  argument to xRea
bdb0: 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  lloc is zero,.**
bdc0: 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62   xRealloc must b
bdd0: 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d  e a no-op - it m
bde0: 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20  ust not perform 
bdf0: 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  any allocation o
be00: 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f  r.** deallocatio
be10: 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72  n.  ^SQLite guar
be20: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
be30: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
be40: 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
be50: 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
be60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
be70: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
be80: 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f  undup..** And so
be90: 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65 20   in cases where 
bea0: 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20  xRoundup always 
beb0: 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
bec0: 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52  ve number,.** xR
bed0: 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f  ealloc can perfo
bee0: 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74 68  rm exactly as th
bef0: 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
bf00: 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ry realloc() and
bf10: 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20  .** still be in 
bf20: 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20  compliance with 
bf30: 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74 69  this specificati
bf40: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  on..**.** xSize 
bf50: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
bf60: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
bf70: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
bf80: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
bf90: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
bfa0: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
bfb0: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
bfc0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
bfd0: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
bfe0: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
bff0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
c000: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
c010: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
c020: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
c030: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
c040: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
c050: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
c060: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c070: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
c080: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
c090: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
c0a0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
c0b0: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
c0c0: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
c0d0: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
c0e0: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
c0f0: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
c100: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
c110: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
c120: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
c130: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
c140: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c150: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
c160: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
c170: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
c180: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
c190: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
c1a0: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
c1b0: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
c1c0: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
c1d0: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
c1e0: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
c1f0: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
c200: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
c210: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
c220: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
c230: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
c240: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
c250: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
c260: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
c270: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
c280: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
c290: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
c2a0: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
c2b0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
c2c0: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
c2d0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
c2e0: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
c2f0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
c300: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
c310: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
c320: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
c330: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
c340: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
c350: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
c360: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
c370: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
c380: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
c390: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
c3a0: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
c3b0: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
c3c0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
c3d0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
c3e0: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
c3f0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
c400: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
c410: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
c420: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
c430: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
c440: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
c450: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
c460: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
c470: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
c480: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
c490: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
c4a0: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
c4b0: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
c4c0: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
c4d0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c4e0: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
c4f0: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
c500: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
c510: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
c520: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
c530: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
c540: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
c550: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
c560: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
c570: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
c580: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
c590: 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
c5a0: 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
c5b0: 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
c5c0: 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
c5d0: 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
c5e0: 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
c5f0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
c600: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
c610: 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
c620: 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
c630: 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
c640: 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
c650: 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
c660: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
c670: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
c680: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
c690: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
c6a0: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
c6b0: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
c6c0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
c6d0: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
c6e0: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
c6f0: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
c700: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
c710: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
c720: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
c730: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
c740: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
c750: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
c760: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
c770: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
c780: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
c790: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
c7a0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
c7b0: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
c7c0: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
c7d0: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
c7e0: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
c7f0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
c800: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
c810: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
c820: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
c830: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
c840: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
c850: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
c860: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
c870: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
c880: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
c890: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
c8a0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
c8b0: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
c8c0: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
c8d0: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
c8e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c8f0: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
c900: 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
c910: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
c920: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
c930: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
c940: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
c950: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
c960: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
c970: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
c980: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c990: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
c9a0: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
c9b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
c9c0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
c9d0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
c9e0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
c9f0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
ca00: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
ca10: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
ca20: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
ca30: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
ca40: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
ca50: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
ca60: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
ca70: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
ca80: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
ca90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
caa0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
cab0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
cac0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
cad0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
cae0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
caf0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
cb00: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
cb10: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
cb20: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
cb30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
cb40: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
cb50: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
cb60: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
cb70: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
cb80: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
cb90: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
cba0: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
cbb0: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
cbc0: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
cbd0: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
cbe0: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
cbf0: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
cc00: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
cc10: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
cc20: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
cc30: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
cc40: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
cc50: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
cc60: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
cc70: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
cc80: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
cc90: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
cca0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
ccb0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
ccc0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
ccd0: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
cce0: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
ccf0: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
cd00: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
cd10: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
cd20: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
cd30: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
cd40: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
cd50: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
cd60: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
cd70: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
cd80: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
cd90: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
cda0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
cdb0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
cdc0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
cdd0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
cde0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
cdf0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
ce00: 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
ce10: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
ce20: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
ce30: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
ce40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ce50: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
ce60: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
ce70: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
ce80: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
ce90: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
cea0: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
ceb0: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
cec0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
ced0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
cee0: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
cef0: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
cf00: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
cf10: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
cf20: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
cf30: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
cf40: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
cf50: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
cf60: 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
cf70: 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
cf80: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
cf90: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
cfa0: 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
cfb0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
cfc0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
cfd0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
cfe0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
cff0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
d000: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
d010: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
d020: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
d030: 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
d040: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
d050: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
d060: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
d070: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
d080: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
d090: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
d0a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
d0b0: 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
d0c0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
d0d0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d0e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d0f0: 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
d100: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
d110: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
d120: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
d130: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
d140: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
d150: 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
d160: 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
d170: 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
d180: 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
d190: 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
d1a0: 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
d1b0: 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
d1c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d1d0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
d1e0: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
d1f0: 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
d200: 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
d210: 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
d220: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
d230: 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
d240: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
d250: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d260: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
d270: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
d280: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
d290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
d2a0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d2b0: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
d2c0: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
d2d0: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
d2e0: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
d2f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d300: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
d310: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
d320: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
d330: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
d340: 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
d350: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
d360: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
d370: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
d380: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
d390: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
d3a0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
d3b0: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
d3c0: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
d3d0: 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
d3e0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d3f0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
d400: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
d410: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
d420: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
d430: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
d440: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d450: 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
d460: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
d470: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d480: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
d490: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
d4a0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
d4b0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
d4c0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
d4d0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
d4e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
d4f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d500: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
d510: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
d520: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
d530: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
d540: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d550: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
d560: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
d570: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
d580: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
d590: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
d5a0: 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
d5b0: 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
d5c0: 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
d5d0: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
d5e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
d5f0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
d600: 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
d610: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
d620: 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
d630: 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
d640: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d650: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
d660: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
d670: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
d680: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
d690: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
d6a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
d6b0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
d6c0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
d6d0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
d6e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d6f0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
d700: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
d710: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
d720: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
d730: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
d740: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
d750: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
d760: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
d770: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
d780: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
d790: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
d7a0: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
d7b0: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
d7c0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
d7d0: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
d7e0: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
d7f0: 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
d800: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
d810: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
d820: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
d830: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d840: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
d850: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
d860: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
d870: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
d880: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
d890: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
d8a0: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
d8b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
d8c0: 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
d8d0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
d8e0: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
d8f0: 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
d900: 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
d910: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
d920: 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
d930: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
d940: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
d950: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
d960: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
d970: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
d980: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
d990: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
d9a0: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
d9b0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
d9c0: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
d9d0: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
d9e0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
d9f0: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
da00: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
da10: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
da20: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
da30: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
da40: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
da50: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
da60: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
da70: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
da80: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
da90: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
daa0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
dab0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
dac0: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
dad0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
dae0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
daf0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
db00: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
db10: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
db20: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
db30: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
db40: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
db50: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
db60: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
db70: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
db80: 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74  e scrach allocat
db90: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
dba0: 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
dbb0: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
dbc0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
dbd0: 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
dbe0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
dbf0: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
dc00: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
dc10: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
dc20: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
dc30: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61   16. The sz para
dc40: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
dc50: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c  a few bytes.** l
dc60: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61  arger than the a
dc70: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70  ctual scratch sp
dc80: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65  ace required due
dc90: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65   to internal ove
dca0: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69  rhead..** The fi
dcb0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
dcc0: 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
dcd0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
dce0: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
dcf0: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
dd00: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
dd10: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
dd20: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
dd30: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
dd40: 66 65 72 20 70 65 72 20 74 68 72 65 61 64 2e 20  fer per thread. 
dd50: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
dd60: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78  be set to the ex
dd70: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
dd80: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
dd90: 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a  .  ^SQLite will.
dda0: 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ** never require
ddb0: 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
ddc0: 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
ddd0: 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68 65 20  han 6 times the 
dde0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
ddf0: 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
de00: 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
de10: 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74 63 68  ditional scratch
de20: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 0a   memory beyond .
de30: 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  ** what is provi
de40: 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
de50: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
de60: 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
de70: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
de80: 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
de90: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
dea0: 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
deb0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
dec0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
ded0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
dee0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
def0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
df00: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
df10: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
df20: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
df30: 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
df40: 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
df50: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
df60: 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  nation.  .** Thi
df70: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
df80: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
df90: 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
dfa0: 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
dfb0: 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
dfc0: 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
dfd0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
dfe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
dff0: 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  E option..** The
e000: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
e010: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
e020: 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
e030: 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
e040: 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
e050: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
e060: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
e070: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
e080: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
e090: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
e0a0: 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
e0b0: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e0c0: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e0d0: 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
e0e0: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
e0f0: 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
e100: 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
e110: 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
e120: 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
e130: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
e140: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
e150: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
e160: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
e170: 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
e180: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
e190: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
e1a0: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
e1b0: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
e1c0: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
e1d0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
e1e0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
e1f0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
e200: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e210: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e220: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
e230: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
e240: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
e250: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
e260: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
e270: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
e280: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
e290: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
e2a0: 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
e2b0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
e2c0: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
e2d0: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
e2e0: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
e2f0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
e300: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
e310: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
e320: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
e330: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
e340: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
e350: 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
e360: 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f  tion might use o
e370: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
e380: 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68  e N buffers to h
e390: 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  old .** memory a
e3a0: 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d  ccounting inform
e3b0: 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74  ation. The point
e3c0: 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
e3d0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
e3e0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e3f0: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
e400: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
e410: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
e420: 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
e430: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
e440: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e450: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
e460: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
e470: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
e480: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
e490: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
e4a0: 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
e4b0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
e4c0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
e4d0: 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
e4e0: 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
e4f0: 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
e500: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
e510: 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
e520: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
e530: 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
e540: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
e550: 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
e560: 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
e570: 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
e580: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
e590: 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
e5a0: 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
e5b0: 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
e5c0: 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
e5d0: 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
e5e0: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
e5f0: 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
e600: 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
e610: 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
e620: 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
e630: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
e640: 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
e650: 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
e660: 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
e670: 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
e680: 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
e690: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
e6a0: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
e6b0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e6c0: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
e6d0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
e6e0: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
e6f0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
e700: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
e710: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
e720: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
e730: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
e740: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
e750: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
e760: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e770: 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
e780: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
e790: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
e7a0: 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
e7b0: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
e7c0: 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
e7d0: 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
e7e0: 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
e7f0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
e800: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e810: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
e820: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
e830: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
e840: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
e850: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
e860: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
e870: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
e880: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
e890: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e8a0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e8b0: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e8c0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e8d0: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
e8e0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
e8f0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
e900: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
e910: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
e920: 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
e930: 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
e940: 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  .** content of t
e950: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
e960: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
e970: 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
e980: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
e990: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
e9a0: 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
e9b0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e9c0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
e9d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
e9e0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e9f0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
ea00: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
ea10: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
ea20: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
ea30: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
ea40: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
ea50: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
ea60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ea70: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
ea80: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
ea90: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
eaa0: 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
eab0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
eac0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ead0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
eae0: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
eaf0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
eb00: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
eb10: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
eb20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
eb30: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
eb40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
eb50: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
eb60: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
eb70: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
eb80: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
eb90: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
eba0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
ebb0: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
ebc0: 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
ebd0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
ebe0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
ebf0: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
ec00: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
ec10: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
ec20: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
ec30: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
ec40: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
ec50: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
ec60: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
ec70: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
ec80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
ec90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
eca0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
ecb0: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
ecc0: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
ecd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
ece0: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
ecf0: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
ed00: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
ed10: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
ed20: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
ed30: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
ed40: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
ed50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ed60: 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
ed70: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
ed80: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
ed90: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
eda0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
edb0: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
edc0: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
edd0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ede0: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
edf0: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
ee00: 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
ee10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ee20: 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
ee30: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
ee40: 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
ee50: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ee60: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
ee70: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
ee80: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
ee90: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
eea0: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
eeb0: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
eec0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
eed0: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
eee0: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
eef0: 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
ef00: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
ef10: 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
ef20: 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
ef30: 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
ef40: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
ef50: 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
ef60: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
ef70: 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
ef80: 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
ef90: 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
efa0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
efb0: 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
efc0: 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
efd0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
efe0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74  ONFIG_PCACHE</dt
eff0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f000: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
f010: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f020: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
f030: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
f040: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f050: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ods] object.  Th
f060: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
f070: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
f080: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
f090: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
f0a0: 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
f0b0: 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
f0c0: 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
f0d0: 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
f0e0: 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
f0f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f100: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ns.</dd>.**.** <
f110: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f120: 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a  _GETPCACHE</dt>.
f130: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f140: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f150: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f160: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f170: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
f180: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f190: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
f1a0: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
f1b0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
f1c0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f1d0: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
f1e0: 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
f1f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f200: 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
f210: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
f220: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
f230: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
f240: 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
f250: 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
f260: 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
f270: 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
f280: 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
f290: 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
f2a0: 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
f2b0: 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
f2c0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
f2d0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
f2e0: 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
f2f0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
f300: 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
f310: 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
f320: 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
f330: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
f340: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
f350: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
f360: 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
f370: 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
f380: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
f390: 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
f3a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
f3b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
f3c0: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
f3d0: 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
f3e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
f3f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
f400: 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
f410: 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
f420: 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
f430: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
f440: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
f450: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
f460: 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
f470: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
f480: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
f490: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
f4a0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
f4b0: 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
f4c0: 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
f4d0: 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
f4e0: 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
f4f0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
f500: 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
f510: 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
f520: 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
f530: 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
f540: 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
f550: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
f560: 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
f570: 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
f580: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
f590: 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
f5a0: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
f5b0: 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
f5c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
f5d0: 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
f5e0: 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
f5f0: 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
f600: 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
f610: 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
f620: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
f630: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
f640: 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
f650: 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
f660: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
f670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f680: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
f690: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
f6a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f6b0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
f6c0: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
f6d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f6e0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
f6f0: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
f700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f710: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
f720: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
f730: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
f740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f750: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
f760: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
f770: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
f780: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f790: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
f7a0: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
f7b0: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
f7c0: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
f7d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f7e0: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
f7f0: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
f800: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
f810: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
f820: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
f830: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
f840: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
f850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f860: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
f870: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
f880: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f890: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
f8a0: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
f8b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f8c0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f8d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f8e0: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
f8f0: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
f900: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
f910: 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
f920: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
f930: 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
f940: 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
f950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f960: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
f970: 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
f980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f990: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
f9a0: 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
f9b0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f9c0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f9d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
f9e0: 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
f9f0: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
fa00: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  e_methods* */.#d
fa10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
fa20: 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
fa30: 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
fa40: 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  oid* */../*.** C
fa50: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
fa60: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
fa70: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
fa80: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
fa90: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
faa0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
fab0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
fac0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
fad0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
fae0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
faf0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
fb00: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fb10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
fb20: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
fb30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
fb40: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
fb50: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
fb60: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
fb70: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
fb80: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
fb90: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
fba0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
fbb0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
fbc0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
fbd0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
fbe0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
fbf0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
fc00: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
fc10: 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
fc20: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
fc30: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
fc40: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
fc50: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
fc60: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
fc70: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
fc80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fc90: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
fca0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
fcb0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
fcc0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
fcd0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
fce0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
fcf0: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
fd00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
fd10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
fd20: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
fd30: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
fd40: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
fd50: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
fd60: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
fd70: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
fd80: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
fd90: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
fda0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
fdb0: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
fdc0: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
fdd0: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
fde0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
fdf0: 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
fe00: 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
fe10: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
fe20: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
fe30: 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
fe40: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
fe50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
fe60: 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
fe70: 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
fe80: 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
fe90: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
fea0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
feb0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
fec0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
fed0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
fee0: 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
fef0: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
ff00: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
ff10: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
ff20: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
ff30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
ff40: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
ff50: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
ff60: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
ff70: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
ff80: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
ff90: 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
ffa0: 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
ffb0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
ffc0: 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
ffd0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
ffe0: 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
fff0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
10000 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
10010 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
10020 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
10030 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
10040 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d  ext smaller.** m
10050 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53  ultiple of 8.  S
10060 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
10070 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
10080 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  E]</dd>.**.** </
10090 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
100a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
100b0 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
100c0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
100d0 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
100e0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
100f0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
10100 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
10110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
10120 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
10130 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
10140 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
10150 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
10160 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10170 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
10180 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
10190 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
101a0 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
101b0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
101c0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
101d0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
101e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
101f0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
10200 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
10210 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
10220 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
10230 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
10240 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
10250 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
10260 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
10270 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
10280 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
10290 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
102a0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
102b0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
102c0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
102d0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
102e0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
102f0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
10300 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
10310 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
10320 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
10330 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
10340 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
10350 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
10360 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
10370 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
10380 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
10390 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
103a0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
103b0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
103c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
103d0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
103e0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
103f0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
10400 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
10410 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
10420 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
10430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
10440 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10450 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
10460 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
10470 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
10480 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
10490 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
104a0 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
104b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
104c0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
104d0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
104e0 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
104f0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
10500 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
10510 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
10520 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
10530 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
10540 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
10550 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
10560 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
10570 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
10580 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
10590 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
105a0 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
105b0 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
105c0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
105d0 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
105e0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
105f0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
10600 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
10610 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
10620 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
10630 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
10640 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
10650 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10660 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
10670 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
10680 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
10690 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
106a0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
106b0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
106c0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
106d0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
106e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
106f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
10700 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
10710 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
10720 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
10730 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
10740 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
10750 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
10760 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
10770 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
10780 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
10790 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
107a0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
107b0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
107c0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
107d0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
107e0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
107f0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
10800 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
10810 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
10820 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
10830 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
10840 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
10850 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
10860 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
10870 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
10880 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
10890 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
108a0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
108b0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
108c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
108d0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
108e0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
108f0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
10900 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
10910 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
10920 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
10930 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
10940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10950 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
10960 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10970 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
10980 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
10990 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
109a0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
109b0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
109c0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
109d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
109e0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
109f0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
10a00 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
10a10 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
10a20 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
10a30 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
10a40 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
10a50 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
10a60 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
10a70 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
10a80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
10a90 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
10aa0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
10ab0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
10ac0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
10ad0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
10ae0 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
10af0 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
10b00 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
10b10 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
10b20 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
10b30 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
10b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
10b50 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
10b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
10b70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
10b80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
10b90 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
10ba0 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
10bb0 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
10bc0 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
10bd0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
10be0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
10bf0 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
10c00 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
10c10 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
10c20 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
10c30 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
10c40 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
10c50 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
10c60 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
10c70 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
10c80 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
10c90 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
10ca0 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
10cb0 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
10cc0 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
10cd0 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
10ce0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
10cf0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
10d00 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
10d10 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
10d20 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
10d30 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
10d40 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
10d50 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
10d60 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
10d70 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
10d80 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
10d90 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
10da0 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
10db0 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
10dc0 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
10dd0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10de0 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
10df0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
10e00 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
10e10 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
10e20 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
10e30 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
10e40 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
10e50 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
10e60 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
10e70 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
10e80 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
10e90 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
10ea0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
10eb0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
10ec0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
10ed0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
10ee0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
10ef0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
10f00 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
10f10 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
10f20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
10f30 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
10f40 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
10f50 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
10f60 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
10f70 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
10f80 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
10f90 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
10fa0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
10fb0 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
10fc0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
10fd0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
10fe0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
10ff0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
11000 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
11010 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
11020 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
11030 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
11040 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
11050 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
11060 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
11070 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
11080 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
11090 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
110a0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
110b0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
110c0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
110d0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
110e0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
110f0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11100 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
11110 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
11120 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
11130 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
11140 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
11150 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
11160 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
11170 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
11180 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
11190 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
111a0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
111b0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
111c0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
111d0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
111e0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
111f0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
11200 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
11210 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
11220 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
11230 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
11240 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
11250 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
11260 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
11270 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
11280 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
11290 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
112a0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
112b0 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
112c0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
112d0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
112e0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
112f0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
11300 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
11310 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
11320 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
11330 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
11340 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
11350 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
11360 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
11370 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
11380 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
11390 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
113a0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
113b0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
113c0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
113d0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
113e0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
113f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11400 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
11410 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
11420 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
11430 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
11440 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
11450 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
11460 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
11470 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
11480 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
11490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
114a0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
114b0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
114c0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
114d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
114e0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
114f0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
11500 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
11510 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
11520 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
11530 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
11540 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
11550 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
11560 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
11570 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11580 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
11590 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
115a0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
115b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
115c0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
115d0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
115e0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
115f0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
11600 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
11610 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
11620 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
11630 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
11640 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
11650 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
11660 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
11670 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
11680 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
11690 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
116a0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
116b0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
116c0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
116d0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
116e0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
116f0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
11700 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
11710 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
11720 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
11730 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
11740 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
11750 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11760 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
11770 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
11780 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
11790 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
117a0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
117b0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
117c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
117d0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
117e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
117f0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
11800 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
11810 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
11820 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
11830 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
11840 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
11850 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
11860 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
11870 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
11880 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
11890 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
118a0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
118b0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
118c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
118d0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
118e0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
118f0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
11900 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
11910 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
11920 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
11930 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
11940 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
11950 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
11960 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
11970 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
11980 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
11990 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
119a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
119b0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
119c0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
119d0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
119e0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
119f0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
11a00 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
11a10 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
11a20 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
11a30 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
11a40 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
11a50 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
11a60 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
11a70 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
11a80 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
11a90 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
11aa0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
11ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
11ac0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
11ad0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
11ae0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
11af0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
11b00 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
11b10 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
11b20 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
11b30 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
11b40 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
11b50 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
11b60 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
11b70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
11b80 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
11b90 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
11ba0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
11bb0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
11bc0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
11bd0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
11be0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
11bf0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
11c00 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
11c10 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
11c20 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
11c30 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
11c40 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
11c50 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
11c60 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
11c70 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
11c80 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
11c90 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
11ca0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
11cb0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
11cc0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
11cd0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
11ce0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
11cf0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
11d00 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
11d10 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
11d20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
11d30 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
11d40 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
11d50 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
11d60 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
11d70 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
11d80 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
11d90 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11da0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
11db0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
11dc0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
11dd0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
11de0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
11df0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
11e00 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
11e10 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
11e20 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
11e30 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
11e40 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11e50 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
11e60 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
11e70 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
11e80 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
11e90 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
11ea0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
11eb0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
11ec0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
11ed0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
11ee0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
11ef0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
11f00 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
11f10 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
11f20 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
11f30 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
11f40 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
11f50 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
11f60 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
11f70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11f80 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
11f90 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
11fa0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
11fb0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
11fc0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
11fd0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
11fe0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
11ff0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
12000 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
12010 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12020 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
12030 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
12040 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12050 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
12060 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
12070 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
12080 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
12090 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
120a0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
120b0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
120c0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
120d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
120e0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
120f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
12100 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
12110 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12120 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
12130 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
12140 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
12150 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
12160 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
12170 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
12180 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
12190 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
121a0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
121b0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
121c0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
121d0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
121e0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
121f0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
12200 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
12210 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
12220 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
12230 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
12240 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
12250 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
12260 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
12270 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
12280 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
12290 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
122a0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
122b0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
122c0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
122d0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
122e0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
122f0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
12300 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
12310 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
12320 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
12330 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
12340 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
12350 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
12360 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
12370 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
12380 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
12390 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
123a0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
123b0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
123c0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
123d0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
123e0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
123f0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
12400 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
12410 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
12420 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
12430 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
12440 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
12450 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
12460 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
12470 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
12480 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
12490 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
124a0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
124b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
124c0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
124d0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
124e0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
124f0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
12500 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
12510 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
12520 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
12530 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
12540 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
12550 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
12560 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
12570 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12580 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
12590 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
125a0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
125b0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
125c0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
125d0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
125e0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
125f0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
12600 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
12610 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
12620 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
12630 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
12640 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
12650 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
12660 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
12670 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
12680 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12690 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
126a0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
126b0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
126c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
126d0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
126e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
126f0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
12700 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
12710 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
12720 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12730 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
12740 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
12750 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
12760 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
12770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
12780 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
12790 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
127a0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
127b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
127c0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
127d0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
127e0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
127f0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
12800 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
12810 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
12820 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
12830 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
12840 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
12850 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
12860 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
12870 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
12880 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
12890 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
128a0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
128b0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
128c0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
128d0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
128e0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
128f0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
12900 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
12910 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
12920 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
12930 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
12940 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
12950 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
12960 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
12970 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
12980 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
12990 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
129a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
129b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
129c0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
129d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
129e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
129f0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
12a00 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
12a10 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
12a20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
12a30 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
12a40 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
12a50 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
12a60 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
12a70 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
12a80 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
12a90 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
12aa0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
12ab0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
12ac0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
12ad0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12ae0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
12af0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
12b00 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
12b10 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
12b20 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
12b30 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
12b40 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
12b50 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
12b60 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
12b70 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
12b80 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
12b90 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
12ba0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
12bb0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
12bc0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
12bd0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
12be0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
12bf0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
12c00 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
12c10 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
12c20 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
12c30 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
12c40 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
12c50 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
12c60 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
12c70 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
12c80 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
12c90 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12ca0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
12cb0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
12cc0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
12cd0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
12ce0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
12cf0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
12d00 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
12d10 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
12d20 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
12d30 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
12d40 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
12d50 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
12d60 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
12d70 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
12d80 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
12d90 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
12da0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
12db0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
12dc0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
12dd0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
12de0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
12df0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
12e00 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
12e10 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
12e20 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
12e30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12e40 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
12e50 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
12e60 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
12e70 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
12e80 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
12e90 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
12ea0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
12eb0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
12ec0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
12ed0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
12ee0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
12ef0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
12f00 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
12f10 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
12f20 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
12f30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
12f40 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
12f50 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
12f60 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
12f70 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
12f80 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
12f90 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
12fa0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
12fb0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
12fc0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
12fd0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
12fe0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
12ff0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
13000 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
13010 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
13020 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
13030 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
13040 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
13050 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
13060 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
13070 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
13080 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
13090 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
130a0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
130b0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
130c0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
130d0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
130e0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
130f0 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
13100 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
13110 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
13120 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
13130 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
13140 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
13150 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
13160 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
13170 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
13180 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
13190 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
131a0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
131b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
131c0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
131d0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
131e0 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
131f0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
13200 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
13210 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
13220 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
13230 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
13240 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
13250 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
13260 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
13270 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
13280 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
13290 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
132a0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
132b0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
132c0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
132d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
132e0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
132f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13300 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
13310 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
13320 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
13330 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
13340 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
13350 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
13360 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
13370 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
13380 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
13390 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
133a0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
133b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
133c0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
133d0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
133e0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
133f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13400 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
13410 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
13420 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
13430 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
13440 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
13450 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
13460 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
13470 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
13480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13490 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
134a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
134b0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
134c0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
134d0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
134e0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
134f0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
13500 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
13510 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
13520 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
13530 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
13540 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
13550 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
13560 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
13570 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
13580 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
13590 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
135a0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
135b0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
135c0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
135d0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
135e0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
135f0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
13600 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
13610 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
13620 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
13630 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
13640 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
13650 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
13660 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
13670 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
13680 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
13690 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
136a0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
136b0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
136c0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
136d0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
136e0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
136f0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
13700 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
13710 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
13720 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
13730 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
13740 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
13750 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
13760 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
13770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13780 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
13790 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
137a0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
137b0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
137c0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
137d0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
137e0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
137f0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
13800 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
13810 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
13820 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
13830 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
13840 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
13850 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
13860 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
13870 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
13880 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
13890 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  es.**.** Definit
138a0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
138b0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
138c0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
138d0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
138e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
138f0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
13900 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
13910 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
13920 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
13930 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
13940 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
13950 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
13960 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
13970 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
13980 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
13990 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
139a0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
139b0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
139c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
139d0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
139e0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
139f0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
13a00 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
13a10 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
13a20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
13a30 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
13a40 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
13a50 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
13a60 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
13a70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
13a80 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
13a90 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
13aa0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
13ab0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
13ac0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
13ad0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
13ae0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
13af0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
13b00 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
13b10 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
13b20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
13b30 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
13b40 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
13b50 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
13b60 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
13b70 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
13b80 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
13b90 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
13ba0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
13bb0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
13bc0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
13bd0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
13be0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
13bf0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
13c00 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
13c10 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
13c20 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
13c30 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
13c40 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
13c50 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
13c60 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
13c70 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
13c80 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
13c90 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
13ca0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
13cb0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
13cc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
13cd0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
13ce0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
13cf0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
13d00 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
13d10 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
13d20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13d30 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
13d40 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
13d50 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
13d60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13d70 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
13d80 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
13d90 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
13da0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
13db0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
13dc0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
13dd0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13de0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
13df0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
13e00 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
13e10 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
13e20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
13e30 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
13e40 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
13e50 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
13e60 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
13e70 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
13e80 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
13e90 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
13ea0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
13eb0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
13ec0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
13ed0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
13ee0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13ef0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
13f00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13f10 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
13f20 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
13f30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
13f40 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
13f50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13f60 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
13f70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13f80 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
13f90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13fa0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
13fb0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13fc0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
13fd0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
13fe0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13ff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
14000 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
14010 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
14020 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
14030 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
14040 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14050 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
14060 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
14070 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
14080 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
14090 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
140a0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
140b0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
140c0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
140d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
140e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
140f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
14100 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
14110 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
14120 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68  able(),.** it sh
14130 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72 65  ould pass the re
14140 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
14150 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
14160 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
14170 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
14180 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
14190 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
141a0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
141b0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
141c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
141d0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
141e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
141f0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
14200 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
14210 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
14220 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
14230 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
14240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
14250 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
14260 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
14270 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
14280 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
14290 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
142a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
142b0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
142c0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
142d0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
142e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
142f0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
14300 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
14310 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
14320 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
14330 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
14340 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
14350 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
14360 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
14370 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
14380 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
14390 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
143a0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
143b0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
143c0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
143d0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
143e0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
143f0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
14400 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
14410 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
14420 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
14430 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
14440 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f  _errmsg()].)^.*/
14450 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
14460 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
14470 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
14480 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
14490 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
144a0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
144b0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
144c0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
144d0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
144e0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
144f0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
14500 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
14510 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
14520 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
14530 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
14540 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
14550 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
14560 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
14570 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
14580 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
14590 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
145a0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
145b0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
145c0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
145d0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
145e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
145f0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
14600 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
14610 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
14620 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
14630 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
14640 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
14650 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
14660 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
14670 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
14680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14690 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
146a0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
146b0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
146c0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
146d0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
146e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
146f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14700 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
14710 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
14720 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
14730 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
14740 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
14750 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
14760 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
14770 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
14780 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
14790 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
147a0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
147b0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
147c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
147d0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
147e0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74  **.** ^(In sqlit
147f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
14800 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
14810 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
14820 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
14830 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
14840 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
14850 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
14860 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
14870 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
14880 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
14890 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
148a0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
148b0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
148c0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
148d0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
148e0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
148f0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
14900 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
14910 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
14920 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
14930 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
14940 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
14950 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
14960 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
14970 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
14980 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
14990 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
149a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
149b0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
149c0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
149d0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
149e0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
149f0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
14a00 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
14a10 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
14a20 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
14a30 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
14a40 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
14a50 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
14a60 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
14a70 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
14a80 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
14a90 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
14aa0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
14ab0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
14ac0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
14ad0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
14ae0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
14af0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
14b00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
14b10 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
14b20 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
14b30 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
14b40 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
14b50 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
14b60 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
14b70 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
14b80 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
14b90 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
14ba0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
14bb0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
14bc0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
14bd0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
14be0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
14bf0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
14c00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
14c10 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
14c20 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
14c30 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
14c40 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
14c50 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
14c60 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
14c70 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
14c80 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
14c90 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
14ca0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
14cb0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
14cc0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
14cd0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
14ce0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
14cf0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
14d00 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
14d10 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
14d20 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
14d30 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
14d40 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
14d50 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
14d60 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
14d70 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
14d80 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
14d90 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
14da0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
14db0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
14dc0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
14dd0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
14de0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
14df0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
14e00 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
14e10 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
14e20 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
14e30 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
14e40 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
14e50 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
14e60 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
14e70 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
14e80 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
14e90 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
14ea0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
14eb0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
14ec0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14ed0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
14ee0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
14ef0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
14f00 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
14f10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14f20 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
14f30 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
14f40 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
14f50 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
14f60 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
14f70 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
14f80 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
14f90 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
14fa0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
14fb0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14fc0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
14fd0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
14fe0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
14ff0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
15000 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
15010 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
15020 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
15030 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
15040 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15050 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
15060 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15070 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
15080 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
15090 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
150a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
150b0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
150c0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
150d0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
150e0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
150f0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
15100 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
15110 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15120 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
15130 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
15140 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
15150 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
15160 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
15170 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
15180 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
15190 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
151a0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
151b0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
151c0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
151d0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
151e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
151f0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
15200 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
15210 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
15220 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
15230 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
15240 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
15250 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
15260 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
15270 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
15280 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
15290 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
152a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
152b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
152c0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
152d0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
152e0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
152f0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
15300 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
15310 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
15320 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15330 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15340 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
15350 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
15360 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
15370 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
15380 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
15390 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
153a0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
153b0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
153c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
153d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
153e0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
153f0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
15400 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
15410 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
15420 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
15430 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
15440 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
15450 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
15460 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
15470 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
15480 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
15490 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
154a0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
154b0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
154c0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
154d0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
154e0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
154f0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
15500 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
15510 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
15520 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15530 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
15540 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
15550 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
15560 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
15570 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
15580 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
15590 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
155a0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
155b0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
155c0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
155d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
155e0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
155f0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
15600 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
15610 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
15620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15630 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
15640 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
15650 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
15660 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
15670 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
15680 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
15690 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
156a0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
156b0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
156c0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
156d0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
156e0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
156f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
15700 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
15710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
15720 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
15730 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
15740 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
15750 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
15760 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
15770 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
15780 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
15790 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
157a0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
157b0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
157c0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
157d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
157e0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
157f0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
15800 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
15810 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
15820 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
15830 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15840 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
15850 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
15860 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
15870 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
15880 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
15890 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
158a0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
158b0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
158c0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
158d0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
158e0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
158f0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
15900 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
15910 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
15920 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
15930 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
15940 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
15950 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
15960 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
15970 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
15980 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
15990 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
159a0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
159b0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
159c0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
159d0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
159e0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
159f0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
15a00 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
15a10 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
15a20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
15a30 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
15a40 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
15a50 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
15a60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
15a70 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
15a80 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
15a90 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
15aa0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
15ab0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
15ac0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
15ad0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
15ae0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15af0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
15b00 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
15b10 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
15b20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
15b30 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
15b40 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
15b50 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
15b60 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
15b70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15b80 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
15b90 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
15ba0 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
15bb0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15bc0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
15bd0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
15be0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
15bf0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
15c00 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
15c10 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
15c20 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
15c30 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
15c40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
15c50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15c60 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
15c70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
15c80 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
15c90 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
15ca0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
15cb0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
15cc0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
15cd0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
15ce0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
15cf0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
15d00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
15d10 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15d20 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
15d30 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
15d40 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15d50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15d60 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
15d70 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
15d80 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
15d90 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
15da0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
15db0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
15dc0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
15dd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
15de0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
15df0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
15e00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
15e10 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
15e20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
15e30 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
15e40 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
15e50 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
15e60 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
15e70 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
15e80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15e90 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
15ea0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
15eb0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
15ec0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
15ed0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
15ee0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
15ef0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
15f00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
15f10 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
15f20 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
15f30 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
15f40 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ry..**.** In SQL
15f50 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
15f60 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
15f70 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
15f80 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
15f90 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
15fa0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
15fb0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
15fc0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
15fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
15fe0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
15ff0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
16000 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
16010 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
16020 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
16030 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
16040 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
16050 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
16060 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
16070 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
16080 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
16090 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
160a0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
160b0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
160c0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
160d0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
160e0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
160f0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
16100 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
16110 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
16120 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
16130 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
16140 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
16150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
16160 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
16170 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
16180 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
16190 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
161a0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
161b0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
161c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
161d0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
161e0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
161f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
16200 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
16210 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
16220 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
16230 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
16240 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
16250 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
16260 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
16270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
16280 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
16290 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
162a0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
162b0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
162c0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
162d0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
162e0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
162f0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
16300 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
16310 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
16320 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
16330 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
16340 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16350 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
16360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
16370 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
16380 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
16390 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
163a0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
163b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
163c0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
163d0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
163e0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
163f0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
16400 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
16410 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
16420 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
16430 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16440 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
16450 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
16460 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
16470 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
16480 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
16490 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
164a0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
164b0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
164c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
164d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
164e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
164f0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
16500 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
16510 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
16520 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
16530 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
16540 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16550 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
16560 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
16570 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
16580 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16590 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
165a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
165b0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
165c0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
165d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
165e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
165f0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
16600 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16610 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
16620 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
16630 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
16640 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
16650 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
16660 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
16670 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
16680 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
16690 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
166a0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
166b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
166c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
166d0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
166e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
166f0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
16700 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
16710 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
16720 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16730 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
16740 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
16750 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
16760 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16770 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
16780 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
16790 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
167a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
167b0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
167c0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
167d0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
167e0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
167f0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
16800 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
16810 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
16820 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
16830 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
16840 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
16850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
16860 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
16870 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
16880 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
16890 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
168a0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
168b0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
168c0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
168d0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
168e0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
168f0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
16900 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
16910 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
16920 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
16930 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
16940 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
16950 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
16960 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
16970 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
16980 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
16990 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
169a0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
169b0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
169c0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
169d0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
169e0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
169f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
16a00 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
16a10 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
16a20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
16a30 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
16a40 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
16a50 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
16a60 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
16a70 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
16a80 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
16a90 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
16aa0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
16ab0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
16ac0 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
16ad0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
16ae0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
16af0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
16b00 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
16b10 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
16b20 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
16b30 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
16b40 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
16b50 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
16b60 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
16b70 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
16b80 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
16b90 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
16ba0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
16bb0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
16bc0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
16bd0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
16be0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
16bf0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
16c00 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
16c10 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
16c20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16c30 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
16c40 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
16c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
16c60 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
16c70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
16c80 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
16c90 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
16ca0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
16cb0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
16cc0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
16cd0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
16ce0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
16cf0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
16d00 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
16d10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16d20 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
16d30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
16d40 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
16d50 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
16d60 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
16d70 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
16d80 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
16d90 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
16da0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
16db0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
16dc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16dd0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
16de0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
16df0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
16e00 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
16e10 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
16e20 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
16e30 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
16e40 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
16e50 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
16e60 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
16e70 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
16e80 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
16e90 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
16ea0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
16eb0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
16ec0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
16ed0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
16ee0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
16ef0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
16f00 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
16f10 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
16f20 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
16f30 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
16f40 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
16f50 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
16f60 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
16f70 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
16f80 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
16f90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
16fa0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
16fb0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
16fc0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
16fd0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
16fe0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
16ff0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
17000 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17010 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
17020 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
17030 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
17040 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
17050 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17060 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17070 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
17080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17090 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
170a0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
170b0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
170c0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
170d0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
170e0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
170f0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
17100 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
17110 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
17120 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17140 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
17150 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
17160 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17170 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17180 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
17190 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
171a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
171b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
171c0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
171d0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
171e0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
171f0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
17200 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
17210 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
17220 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
17230 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
17240 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
17250 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
17260 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17270 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
17280 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
17290 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
172a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
172b0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
172c0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
172d0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
172e0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
172f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17300 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17310 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
17320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
17330 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
17340 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
17350 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
17360 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
17370 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
17380 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
17390 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
173a0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
173b0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
173c0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
173d0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
173e0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
173f0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
17400 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
17410 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
17420 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
17430 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
17440 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
17450 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
17460 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
17470 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
17480 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
17490 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
174a0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
174b0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
174c0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
174d0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
174e0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
174f0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
17500 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
17510 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
17520 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
17530 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
17540 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
17550 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
17560 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
17570 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
17580 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17590 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
175a0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
175b0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
175c0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
175d0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
175e0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
175f0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
17600 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
17610 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
17620 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
17630 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
17640 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
17650 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
17660 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
17670 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
17680 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
17690 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
176a0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
176b0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
176c0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
176d0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
176e0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
176f0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
17700 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
17710 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
17720 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
17730 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
17740 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
17750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
17760 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
17770 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
17780 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
17790 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
177a0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
177b0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
177c0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
177d0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
177e0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
177f0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
17800 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
17810 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
17820 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
17830 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
17840 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
17850 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
17860 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
17870 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
17880 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
17890 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
178a0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
178b0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
178c0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
178d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
178e0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
178f0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
17900 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17910 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
17920 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
17930 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
17940 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
17950 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
17960 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
17970 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
17980 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
17990 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
179a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
179b0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
179c0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
179d0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
179e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
179f0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
17a00 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
17a10 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
17a20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
17a30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
17a40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
17a50 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
17a60 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
17a70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
17a80 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
17a90 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
17aa0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
17ab0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
17ac0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17ad0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
17ae0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
17af0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
17b00 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
17b10 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
17b20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
17b30 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
17b40 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
17b50 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
17b60 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
17b70 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
17b80 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
17b90 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
17ba0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
17bb0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
17bc0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
17bd0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
17be0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17bf0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
17c00 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
17c10 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
17c20 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
17c30 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
17c40 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
17c50 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
17c60 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
17c70 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
17c80 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
17c90 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
17ca0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
17cb0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
17cc0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
17cd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17ce0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
17cf0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
17d00 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
17d10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17d20 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17d30 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
17d40 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
17d50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
17d60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
17d70 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
17d80 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
17d90 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
17da0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
17db0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
17dc0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
17dd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17de0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17df0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
17e00 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
17e10 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
17e20 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
17e30 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
17e40 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
17e50 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
17e60 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
17e70 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
17e80 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
17e90 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
17ea0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17eb0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
17ec0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
17ed0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
17ee0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
17ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
17f00 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
17f10 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
17f20 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
17f30 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
17f40 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
17f50 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
17f60 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
17f70 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
17f80 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
17f90 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
17fa0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
17fb0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
17fc0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17fd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
17fe0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
17ff0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
18000 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
18010 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
18020 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
18030 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
18040 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
18050 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
18060 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
18070 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
18080 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
18090 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
180a0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
180b0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
180c0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
180d0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
180e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
180f0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
18100 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
18110 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
18120 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
18130 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
18140 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
18150 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
18160 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
18170 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
18180 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
18190 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
181a0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
181b0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
181c0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
181d0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
181e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
181f0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
18200 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
18210 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
18220 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
18230 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
18240 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
18250 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
18260 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
18270 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
18280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
18290 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
182a0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
182b0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
182c0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
182d0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
182e0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
182f0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
18300 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
18310 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
18320 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
18330 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
18340 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
18350 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18360 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18370 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
18380 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
18390 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
183a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
183b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
183c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
183d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
183e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
183f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18400 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
18410 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18420 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18430 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18440 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18450 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
18460 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18470 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18480 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18490 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
184a0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
184b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
184c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
184d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
184e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
184f0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
18500 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18510 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18520 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18530 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
18540 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
18550 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18560 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18580 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
18590 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
185a0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
185b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
185c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
185d0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
185e0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
185f0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
18600 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18620 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
18630 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
18640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18650 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18670 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
18680 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
18690 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
186a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
186b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
186c0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
186d0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
186e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
186f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18710 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
18720 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
18730 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18740 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18760 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
18770 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
18780 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18790 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
187a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
187b0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
187c0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
187d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
187e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
187f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18800 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
18810 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
18820 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
18830 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18840 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18850 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
18860 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
18870 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
18880 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18890 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
188a0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
188b0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
188c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
188d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
188e0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
188f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
18900 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18910 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18920 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18930 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
18940 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
18950 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
18960 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
18970 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
18980 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
18990 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
189a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
189b0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
189c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
189d0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
189e0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
189f0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
18a00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18a10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18a20 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
18a30 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
18a40 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
18a50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18a70 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
18a80 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
18a90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18aa0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
18ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ac0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
18ad0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
18ae0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
18af0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18b10 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
18b20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
18b30 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
18b40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b60 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
18b70 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
18b80 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
18b90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
18bb0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
18bc0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
18bd0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
18be0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
18c00 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
18c10 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
18c20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18c30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18c50 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
18c60 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
18c70 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
18c80 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18ca0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
18cb0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
18cc0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
18cd0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
18ce0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
18cf0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
18d00 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
18d10 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
18d20 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
18d30 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
18d40 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
18d50 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
18d60 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
18d70 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
18d80 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
18d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
18da0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
18db0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
18dc0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
18dd0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
18de0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
18df0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
18e00 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
18e10 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
18e20 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
18e30 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
18e40 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
18e50 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
18e60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
18e70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
18e80 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
18e90 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
18ea0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
18eb0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
18ec0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
18ed0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
18ee0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
18ef0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
18f00 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
18f10 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
18f20 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
18f30 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
18f40 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
18f50 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
18f60 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
18f70 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
18f80 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
18f90 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
18fa0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
18fb0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
18fc0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
18fd0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
18fe0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
18ff0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
19000 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
19010 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
19020 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
19030 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
19040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
19050 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
19060 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
19070 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
19080 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
19090 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
190a0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
190b0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
190c0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
190d0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
190e0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
190f0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
19100 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
19110 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
19120 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
19130 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  to run..*/.void 
19140 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
19150 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
19160 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
19170 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
19180 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
19190 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
191a0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
191b0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
191c0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
191d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
191e0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
191f0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19200 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
19210 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
19220 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
19230 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
19240 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19250 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
19260 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
19270 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
19280 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
19290 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
192a0 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
192b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
192c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
192d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
192e0 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e  et_table()].  An
192f0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
19300 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
19310 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
19320 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
19330 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
19340 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
19350 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19360 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19370 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
19380 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
19390 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
193a0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
193b0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
193c0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
193d0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
193e0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
193f0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
19400 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  s handler must n
19410 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
19420 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
19430 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
19440 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19450 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
19460 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
19470 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
19480 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19490 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
194a0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
194b0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
194c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
194d0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
194e0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
194f0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
19500 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
19510 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
19520 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
19530 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
19540 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
19550 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
19560 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
19570 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
19580 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
19590 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
195a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
195b0 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
195c0 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
195d0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
195e0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
195f0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
19600 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
19610 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
19620 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
19630 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
19640 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
19650 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
19660 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
19670 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
19680 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19690 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
196a0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
196b0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
196c0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
196d0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
196e0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
196f0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
19700 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
19710 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
19720 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
19730 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
19740 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
19750 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
19760 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
19770 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
19780 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
19790 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
197a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
197b0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
197c0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
197d0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
197e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
197f0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
19800 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
19810 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
19820 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
19830 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
19840 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
19850 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
19860 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
19870 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
19880 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
19890 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
198a0 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
198b0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
198c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
198d0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
198e0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
198f0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
19900 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
19910 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
19920 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
19930 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
19940 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
19950 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
19960 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
19970 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
19980 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
19990 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
199a0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
199b0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
199c0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
199d0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
199e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
199f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
19a00 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
19a10 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
19a20 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
19a30 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
19a40 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
19a50 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
19a60 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
19a70 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
19a80 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
19a90 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
19aa0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
19ab0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
19ac0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
19ad0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
19ae0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
19af0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
19b00 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
19b10 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
19b20 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
19b30 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
19b40 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
19b50 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
19b60 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
19b70 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
19b80 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
19b90 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
19ba0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
19bb0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
19bc0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
19bd0 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53  E],.** and/or [S
19be0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
19bf0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29  TECACHE] flags:)
19c00 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
19c10 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
19c20 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
19c30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
19c40 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19c50 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
19c60 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
19c70 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
19c80 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
19c90 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
19ca0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
19cb0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
19cc0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
19cd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
19ce0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
19cf0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
19d00 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
19d10 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
19d20 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
19d30 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
19d40 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
19d50 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
19d60 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
19d70 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
19d80 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
19d90 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
19da0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
19db0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
19dc0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
19dd0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
19de0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
19df0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
19e00 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
19e10 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
19e20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
19e30 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
19e40 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
19e50 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
19e60 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
19e70 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
19e80 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
19e90 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19ea0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19eb0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
19ec0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
19ed0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
19ee0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19ef0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
19f00 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
19f10 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
19f20 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e  hown above or on
19f30 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61  e of the combina
19f40 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
19f50 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69  e combined.** wi
19f60 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
19f70 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
19f80 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
19f90 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTEX],.** [SQLIT
19fa0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
19fb0 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  HE] and/or [SQLI
19fc0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
19fd0 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74  CHE] flags,.** t
19fe0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
19ff0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1a000 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
1a010 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1a020 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1a030 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1a040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1a050 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1a060 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1a070 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1a080 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1a090 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1a0a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1a0b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1a0c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1a0d0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
1a0e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1a0f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
1a100 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1a110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
1a120 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
1a130 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1a140 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
1a150 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
1a160 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
1a170 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
1a180 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1a190 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
1a1a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1a1b0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
1a1c0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1a1d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1a1e0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
1a1f0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
1a200 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
1a210 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1a220 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
1a230 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
1a240 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
1a250 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1a260 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
1a270 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1a280 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1a290 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1a2a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a2b0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
1a2c0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
1a2d0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
1a2e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
1a2f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  abled..**.** ^If
1a300 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1a310 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1a320 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1a330 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1a340 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1a350 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1a360 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
1a370 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
1a380 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
1a390 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
1a3a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a3b0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
1a3c0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1a3d0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1a3e0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
1a3f0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
1a400 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
1a410 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
1a420 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
1a430 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
1a440 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
1a450 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1a460 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
1a470 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
1a480 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
1a490 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
1a4a0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
1a4b0 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
1a4c0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
1a4d0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
1a4e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1a4f0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1a500 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1a510 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1a520 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1a530 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1a540 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
1a550 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1a560 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1a570 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1a580 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1a590 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a5a0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1a5b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
1a5c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1a5d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a5e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1a5f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1a600 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
1a610 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
1a620 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1a630 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
1a640 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1a650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
1a660 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
1a670 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1a680 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
1a690 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
1a6a0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1a6b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
1a6c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  used..**.** <b>N
1a6d0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
1a6e0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
1a6f0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
1a700 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1a710 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
1a720 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1a730 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a740 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
1a750 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
1a760 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
1a770 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
1a780 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
1a790 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
1a7a0 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
1a7b0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
1a7c0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
1a7d0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
1a7e0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
1a7f0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1a800 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
1a810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1a820 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
1a830 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1a840 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1a850 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1a860 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1a870 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1a880 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1a890 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1a8a0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
1a8b0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
1a8c0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1a8d0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1a8e0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
1a8f0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1a900 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1a910 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1a920 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1a930 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
1a940 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1a950 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1a960 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1a970 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
1a980 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1a990 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1a9a0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
1a9b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1a9c0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
1a9d0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
1a9e0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1a9f0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
1aa00 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
1aa10 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
1aa20 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
1aa30 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1aa40 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1aa50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1aa60 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1aa70 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1aa80 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1aa90 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1aaa0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1aab0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1aac0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1aad0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1aae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1aaf0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1ab00 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1ab10 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1ab20 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1ab30 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1ab40 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1ab50 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1ab60 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1ab70 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
1ab80 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1ab90 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
1aba0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
1abb0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
1abc0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
1abd0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1abe0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
1abf0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
1ac00 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
1ac10 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
1ac20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
1ac30 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
1ac40 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
1ac50 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1ac60 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
1ac70 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
1ac80 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
1ac90 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1aca0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1acb0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
1acc0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
1acd0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
1ace0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
1acf0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1ad00 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
1ad10 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
1ad20 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
1ad30 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
1ad40 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
1ad50 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
1ad60 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
1ad70 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
1ad80 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1ad90 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
1ada0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1adb0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  s.)^.**.** When 
1adc0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1add0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1ade0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
1adf0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
1ae00 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
1ae10 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
1ae20 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1ae30 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
1ae40 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
1ae50 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
1ae60 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
1ae70 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
1ae80 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
1ae90 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
1aea0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
1aeb0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
1aec0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
1aed0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
1aee0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
1aef0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
1af00 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
1af10 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
1af20 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
1af30 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
1af40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
1af50 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
1af60 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
1af70 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
1af80 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
1af90 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
1afa0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
1afb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1afc0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
1afd0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1afe0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
1aff0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
1b000 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
1b010 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
1b020 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
1b030 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
1b040 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
1b050 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1b060 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
1b070 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
1b080 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
1b090 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
1b0a0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
1b0b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
1b0c0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
1b0d0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
1b0e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
1b0f0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1b100 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
1b110 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
1b120 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
1b130 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1b140 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
1b150 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1b160 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b170 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b180 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1b190 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1b1a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1b1b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b1c0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
1b1d0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
1b1e0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
1b1f0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
1b200 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
1b210 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
1b220 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
1b230 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
1b240 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
1b250 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
1b260 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
1b270 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
1b280 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
1b290 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
1b2a0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
1b2b0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
1b2c0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
1b2d0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
1b2e0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
1b2f0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1b300 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b310 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
1b320 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
1b330 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
1b340 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
1b350 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
1b360 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
1b370 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
1b380 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
1b390 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
1b3a0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
1b3b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
1b3c0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
1b3d0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
1b3e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
1b3f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1b400 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
1b410 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
1b420 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
1b430 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
1b440 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
1b450 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
1b460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1b470 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
1b480 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
1b490 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
1b4a0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
1b4b0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
1b4c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1b4d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
1b4e0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1b4f0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
1b500 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
1b510 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
1b520 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
1b530 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1b540 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1b550 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1b560 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1b570 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1b580 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1b590 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1b5a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b5b0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1b5c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b5d0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1b5e0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1b5f0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1b600 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1b610 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1b620 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1b630 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1b640 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1b650 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1b660 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1b670 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1b680 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1b690 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1b6a0 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1b6b0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1b6c0 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a  ld limit.)^.**.*
1b6d0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
1b6e0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1b6f0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1b700 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1b710 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c  ..** ^(For the l
1b720 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
1b730 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
1b740 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  Z there is a .**
1b750 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
1b760 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
1b770 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
1b780 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65  -time C preproce
1b790 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64  ssor macro named
1b7a0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53   .** [limits | S
1b7b0 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a  QLITE_MAX_XYZ]..
1b7c0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1b7d0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1b7e0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1b7f0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
1b800 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1b810 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1b820 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1b830 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1b840 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1b850 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1b860 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  bound..**.** Run
1b870 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
1b880 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
1b890 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
1b8a0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
1b8b0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
1b8c0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1b8d0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
1b8e0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
1b8f0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
1b900 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
1b910 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
1b920 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
1b930 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
1b940 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
1b950 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
1b960 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
1b970 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
1b980 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
1b990 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
1b9a0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
1b9b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
1b9c0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
1b9d0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
1b9e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1b9f0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
1ba00 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
1ba10 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
1ba20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
1ba30 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
1ba40 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
1ba50 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
1ba60 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
1ba70 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
1ba80 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
1ba90 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
1baa0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
1bab0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
1bac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
1bad0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
1bae0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
1baf0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
1bb00 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
1bb10 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
1bb20 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
1bb30 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
1bb40 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
1bb50 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
1bb60 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
1bb70 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1bb80 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
1bb90 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
1bba0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
1bbb0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
1bbc0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
1bbd0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1bbe0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1bbf0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1bc00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1bc10 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1bc20 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
1bc30 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
1bc40 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
1bc50 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
1bc60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
1bc70 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
1bc80 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
1bc90 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1bca0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
1bcb0 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
1bcc0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
1bcd0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
1bce0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
1bcf0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
1bd00 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
1bd10 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
1bd20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1bd30 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
1bd40 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
1bd50 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
1bd60 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  <dl>.** ^(<dt>SQ
1bd70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1bd80 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1bd90 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
1bda0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
1bdb0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
1bdc0 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  w.<dd>)^.**.** ^
1bdd0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1bde0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
1bdf0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1be00 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
1be10 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
1be20 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
1be30 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1be40 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1be50 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1be60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1be70 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1be80 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1be90 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1bea0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
1beb0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
1bec0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1bed0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
1bee0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
1bef0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
1bf00 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
1bf10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1bf20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1bf30 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1bf40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1bf50 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1bf60 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1bf70 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1bf80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1bf90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1bfa0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
1bfb0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1bfc0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
1bfd0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
1bfe0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
1bff0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1c000 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c010 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
1c020 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c030 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
1c040 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
1c050 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1c060 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
1c070 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
1c080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1c090 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c0a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1c0b0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1c0c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c0d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1c0e0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1c0f0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
1c100 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c110 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1c120 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c130 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c140 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1c150 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1c160 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28  )^</dd>.**.** ^(
1c170 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c180 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1c190 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1c1a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1c1b0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1c1c0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1c1d0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
1c1e0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
1c1f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c200 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c210 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1c220 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1c230 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c240 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
1c250 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c260 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
1c270 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a 2a   bound.</dd>)^.*
1c280 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c290 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
1c2a0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1c2b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1c2c0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
1c2d0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
1c2e0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1c2f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c300 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
1c310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c320 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
1c330 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1c340 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1c350 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1c360 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
1c370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c380 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1c390 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1c3a0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1c3b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1c3c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1c3d0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
1c3e0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1c3f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1c400 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
1c410 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
1c420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1c430 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
1c440 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
1c450 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
1c460 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
1c470 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
1c480 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1c490 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1c4a0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
1c4b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c4c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1c4d0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
1c4e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c4f0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
1c500 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
1c510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1c520 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
1c530 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
1c540 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
1c550 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
1c560 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
1c570 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
1c580 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
1c590 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
1c5a0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
1c5b0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
1c5c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
1c5d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1c5e0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
1c5f0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
1c600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
1c610 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
1c620 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
1c630 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1c640 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1c650 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
1c660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
1c670 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
1c680 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c690 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
1c6a0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
1c6b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1c6c0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
1c6d0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1c6e0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
1c6f0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
1c700 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1c710 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
1c720 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
1c730 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c740 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
1c750 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
1c760 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1c770 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
1c780 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1c790 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
1c7a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
1c7b0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
1c7c0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
1c7d0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
1c7e0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
1c7f0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1c800 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
1c810 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1c820 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
1c830 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
1c840 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
1c850 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
1c860 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
1c870 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
1c880 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
1c890 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
1c8a0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
1c8b0 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
1c8c0 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
1c8d0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
1c8e0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1c8f0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
1c900 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
1c910 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
1c920 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
1c930 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
1c940 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
1c950 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
1c960 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
1c970 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
1c980 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
1c990 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
1c9a0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
1c9b0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1c9c0 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
1c9d0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
1c9e0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
1c9f0 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a  tor bytes..**.**
1ca00 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
1ca10 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
1ca20 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1ca30 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1ca40 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
1ca50 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
1ca60 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1ca70 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1ca80 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1ca90 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
1caa0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
1cab0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1cac0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1cad0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
1cae0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
1caf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
1cb00 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
1cb10 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
1cb20 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
1cb30 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
1cb40 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
1cb50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1cb60 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
1cb70 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
1cb80 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
1cb90 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
1cba0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
1cbb0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
1cbc0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
1cbd0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
1cbe0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
1cbf0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
1cc00 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
1cc10 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
1cc20 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
1cc30 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
1cc40 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
1cc50 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1cc60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1cc70 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
1cc80 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1cc90 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
1cca0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
1ccb0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
1ccc0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
1ccd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
1cce0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
1ccf0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1cd00 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
1cd10 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1cd20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1cd30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1cd40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
1cd50 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1cd60 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
1cd70 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
1cd80 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
1cd90 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
1cda0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
1cdb0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
1cdc0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
1cdd0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1cde0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
1cdf0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
1ce00 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
1ce10 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1ce20 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1ce30 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
1ce40 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
1ce50 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
1ce60 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
1ce70 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
1ce80 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
1ce90 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
1cea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ceb0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
1cec0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
1ced0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
1cee0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
1cef0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
1cf00 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1cf10 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
1cf20 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
1cf30 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1cf40 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
1cf50 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
1cf60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1cf70 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
1cf80 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
1cf90 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
1cfa0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
1cfb0 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 68 65   again.  ^If the
1cfc0 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1cfd0 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1cfe0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1cff0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1d000 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1d010 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1d020 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1d030 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1d040 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1d050 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1d060 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1d070 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1d080 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1d090 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1d0a0 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1d0b0 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1d0c0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1d0d0 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1d0e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1d0f0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1d100 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1d110 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1d120 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1d130 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1d140 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1d150 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
1d160 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1d170 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
1d180 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
1d190 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
1d1a0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
1d1b0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
1d1c0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
1d1d0 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
1d1e0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
1d1f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1d200 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
1d210 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
1d220 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1d230 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
1d240 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
1d250 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
1d260 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
1d270 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1d280 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
1d290 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
1d2a0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
1d2b0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
1d2c0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
1d2d0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
1d2e0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
1d2f0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
1d300 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
1d310 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1d320 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
1d330 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
1d340 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70  he value of a [p
1d350 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1d360 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1d370 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  e WHERE clause m
1d380 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ight.** change t
1d390 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  he query plan fo
1d3a0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  r a statement, t
1d3b0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
1d3c0 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f  t may be.** auto
1d3d0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1d3e0 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 72  iled (as if ther
1d3f0 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 68  e had been a sch
1d400 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74  ema change) on t
1d410 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71  he first .** [sq
1d420 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1d430 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1d440 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a   change to the .
1d450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1d460 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
1d470 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65  ] of the [parame
1d480 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ter]. .** </li>.
1d490 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
1d4a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1d4b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1d4c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1d4d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1d4e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1d4f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1d500 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1d510 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1d520 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1d530 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1d540 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1d550 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1d560 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1d570 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1d580 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1d590 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1d5a0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1d5b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1d5c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1d5d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1d5e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1d5f0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1d600 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1d610 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1d620 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1d630 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1d640 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1d650 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1d660 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1d670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1d680 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1d690 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1d6a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1d6b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1d6c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1d6d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d6e0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1d6f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1d700 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1d710 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1d720 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1d730 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1d740 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1d750 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1d760 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1d770 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1d780 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1d790 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1d7a0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1d7b0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1d7c0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1d7d0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1d7e0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1d7f0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1d800 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1d810 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1d820 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1d830 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1d840 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1d850 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1d860 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1d870 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d880 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1d890 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1d8a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1d8b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1d8c0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1d8d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1d8e0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1d8f0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1d900 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1d910 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1d920 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1d930 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1d940 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1d950 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1d960 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d970 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1d980 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1d990 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1d9a0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1d9b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1d9c0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1d9d0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
1d9e0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
1d9f0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
1da00 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
1da10 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
1da20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
1da30 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
1da40 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
1da50 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
1da60 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
1da70 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
1da80 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1da90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1daa0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1dab0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
1dac0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1dad0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
1dae0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1daf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1db00 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
1db10 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
1db20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
1db30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1db40 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
1db50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1db60 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
1db70 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
1db80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
1db90 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
1dba0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
1dbb0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
1dbc0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
1dbd0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1dbe0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
1dbf0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
1dc00 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
1dc10 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
1dc20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1dc30 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
1dc40 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
1dc50 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
1dc60 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
1dc70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
1dc80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1dc90 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
1dca0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
1dcb0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
1dcc0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
1dcd0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
1dce0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1dcf0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
1dd00 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
1dd10 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
1dd20 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
1dd30 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1dd40 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
1dd50 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
1dd60 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
1dd70 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
1dd80 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
1dd90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
1dda0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
1ddb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ddc0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
1ddd0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
1dde0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
1ddf0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
1de00 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
1de10 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
1de20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  A internal mutex
1de30 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
1de40 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1de50 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1de60 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
1de70 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
1de80 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1de90 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1dea0 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
1deb0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
1dec0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
1ded0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
1dee0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
1def0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
1df00 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
1df10 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
1df20 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
1df30 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
1df40 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
1df50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
1df60 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
1df70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
1df80 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
1df90 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
1dfa0 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
1dfb0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1dfc0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1dfd0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1dfe0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
1dff0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
1e000 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
1e010 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
1e020 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
1e030 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
1e040 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1e050 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
1e060 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
1e070 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1e080 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  ween between pro
1e090 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1e0a0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1e0b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1e0c0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
1e0d0 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
1e0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e0f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e100 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1e110 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1e120 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1e130 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1e140 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1e150 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1e160 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1e170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e180 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1e190 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1e1a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1e1b0 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1e1c0 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1e1d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1e1e0 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1e1f0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1e200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1e210 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1e220 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1e230 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1e240 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1e250 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1e260 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1e270 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1e280 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1e290 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e2a0 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1e2b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1e2c0 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1e2d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e2e0 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1e2f0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
1e300 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
1e310 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
1e320 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
1e330 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
1e340 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
1e350 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
1e360 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1e370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1e380 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1e390 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1e3a0 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1e3b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1e3c0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1e3d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1e3e0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1e3f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1e400 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1e410 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1e420 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1e430 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1e440 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1e450 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1e460 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1e470 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1e480 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1e490 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1e4a0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1e4b0 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1e4c0 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1e4d0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1e4e0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1e4f0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1e500 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1e510 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1e520 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1e530 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1e540 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1e550 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
1e560 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
1e570 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
1e580 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
1e590 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1e5a0 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
1e5b0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
1e5c0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
1e5d0 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
1e5e0 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
1e5f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1e600 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
1e610 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e620 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
1e630 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
1e640 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
1e650 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
1e660 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
1e670 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
1e680 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
1e690 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1e6a0 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
1e6b0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
1e6c0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
1e6d0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
1e6e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
1e6f0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
1e700 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
1e710 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
1e720 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1e730 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
1e740 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
1e750 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54  identifer.)^  ^T
1e760 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
1e770 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
1e780 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
1e790 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1e7a0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
1e7b0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
1e7c0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
1e7d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1e7e0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
1e7f0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
1e800 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1e810 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1e820 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1e830 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1e840 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1e850 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1e860 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1e870 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1e880 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e890 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e8a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
1e8b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1e8c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1e8d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1e8e0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
1e8f0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1e900 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1e910 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
1e920 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1e930 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1e940 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1e950 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1e960 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1e970 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1e980 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1e990 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1e9a0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1e9b0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
1e9c0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1e9d0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1e9e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1e9f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ea00 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
1ea10 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1ea20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
1ea30 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
1ea40 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
1ea50 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
1ea60 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
1ea70 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
1ea80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
1ea90 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
1eaa0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
1eab0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1eac0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
1ead0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
1eae0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1eaf0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
1eb00 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
1eb10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1eb20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
1eb30 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1eb40 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1eb50 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1eb60 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1eb70 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1eb80 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1eb90 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1eba0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1ebb0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1ebc0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1ebd0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1ebe0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
1ebf0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1ec00 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
1ec10 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
1ec20 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
1ec30 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
1ec40 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
1ec50 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1ec60 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1ec70 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
1ec80 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1ec90 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1eca0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1ecb0 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1ecc0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1ecd0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1ece0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1ecf0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1ed00 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1ed10 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1ed20 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20 74  d with it. ^If t
1ed30 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1ed40 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
1ed50 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
1ed60 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
1ed70 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
1ed80 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
1ed90 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
1eda0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
1edb0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
1edc0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
1edd0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
1ede0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1edf0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1ee00 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1ee10 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1ee20 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1ee30 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1ee40 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1ee50 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1ee60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1ee70 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1ee80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1ee90 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1eea0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1eeb0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1eec0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1eed0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1eee0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
1eef0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
1ef00 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
1ef10 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
1ef20 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
1ef30 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
1ef40 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
1ef50 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
1ef60 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
1ef70 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
1ef80 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
1ef90 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
1efa0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
1efb0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
1efc0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1efd0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
1efe0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
1eff0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
1f000 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1f010 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1f020 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1f030 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
1f040 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
1f050 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1f060 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1f070 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1f080 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
1f090 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f0a0 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
1f0b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f0c0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
1f0d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
1f0e0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
1f0f0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
1f100 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
1f110 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
1f120 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
1f130 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
1f140 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
1f150 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
1f160 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
1f170 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1f180 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
1f190 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
1f1a0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
1f1b0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1f1c0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
1f1d0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
1f1e0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
1f1f0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1f200 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
1f210 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
1f220 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1f230 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1f240 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
1f250 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
1f260 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1f270 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
1f280 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
1f290 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
1f2a0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1f2b0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
1f2c0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
1f2d0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1f2e0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
1f2f0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
1f300 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
1f310 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
1f320 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
1f330 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1f340 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f350 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
1f360 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f370 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1f380 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
1f390 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1f3a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1f3b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1f3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f3d0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1f3e0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1f3f0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1f400 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
1f410 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1f420 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
1f430 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f440 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
1f450 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
1f460 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1f470 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
1f480 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
1f490 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
1f4a0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
1f4b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f4c0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1f4d0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
1f4e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1f4f0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
1f500 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f510 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f520 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
1f530 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1f540 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1f550 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1f560 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f570 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
1f580 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1f590 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
1f5a0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1f5b0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
1f5c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f5d0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1f5e0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1f5f0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
1f600 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
1f610 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1f620 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1f630 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
1f640 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
1f650 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f660 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
1f670 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1f680 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1f690 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1f6a0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1f6b0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1f6c0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1f6d0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1f6e0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1f6f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1f700 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1f710 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1f720 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1f730 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
1f740 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
1f750 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
1f760 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
1f770 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
1f780 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
1f790 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
1f7a0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
1f7b0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
1f7c0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
1f7d0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
1f7e0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
1f7f0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
1f800 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
1f810 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
1f820 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
1f830 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1f840 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1f850 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1f860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f870 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f880 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1f890 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f8a0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
1f8b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f8c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1f8d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1f8e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f8f0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1f900 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
1f910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
1f920 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1f930 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
1f940 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
1f950 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
1f960 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
1f970 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
1f980 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
1f990 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
1f9a0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1f9b0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
1f9c0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
1f9d0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
1f9e0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
1f9f0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
1fa00 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
1fa10 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
1fa20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1fa30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1fa40 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
1fa50 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
1fa60 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
1fa70 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
1fa80 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
1fa90 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
1faa0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
1fab0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
1fac0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
1fad0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
1fae0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
1faf0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
1fb00 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
1fb10 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
1fb20 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
1fb30 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1fb40 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
1fb50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
1fb60 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
1fb70 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
1fb80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1fb90 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
1fba0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
1fbb0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
1fbc0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
1fbd0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
1fbe0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
1fbf0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
1fc00 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
1fc10 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
1fc20 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
1fc30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fc40 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1fc50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1fc60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1fc70 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1fc80 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1fc90 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1fca0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1fcb0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1fcc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1fcd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1fce0 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
1fcf0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
1fd00 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1fd10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fd20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1fd30 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
1fd40 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
1fd50 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
1fd60 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
1fd70 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
1fd80 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
1fd90 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
1fda0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
1fdb0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
1fdc0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
1fdd0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
1fde0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1fdf0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1fe00 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
1fe10 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
1fe20 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
1fe30 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
1fe40 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
1fe50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
1fe60 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
1fe70 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
1fe80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1fe90 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
1fea0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
1feb0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
1fec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fed0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1fee0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1fef0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1ff00 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1ff10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1ff20 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1ff30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1ff40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ff50 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1ff60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1ff70 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
1ff80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
1ff90 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
1ffa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ffb0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
1ffc0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
1ffd0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
1ffe0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
1fff0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
20000 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
20010 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
20020 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
20030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20040 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
20050 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20060 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
20070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
20080 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
20090 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
200a0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
200b0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
200c0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
200d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
200e0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
200f0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
20100 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
20110 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
20120 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
20130 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
20140 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
20150 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20160 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
20170 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
20180 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
20190 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
201a0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
201b0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
201c0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
201d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
201e0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
201f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
20200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20210 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
20220 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
20230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
20240 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
20250 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
20260 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
20270 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
20280 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
20290 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
202a0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
202b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
202c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
202d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
202e0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
202f0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
20300 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
20310 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
20320 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20330 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
20340 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
20350 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
20360 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
20370 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
20380 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
20390 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
203a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
203b0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
203c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
203d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
203e0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
203f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
20400 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
20410 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
20420 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
20430 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
20440 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
20450 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
20460 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
20470 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
20480 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
20490 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
204a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
204b0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
204c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
204d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
204e0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
204f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
20500 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
20510 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
20520 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
20530 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
20540 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
20550 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
20560 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
20570 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
20580 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
20590 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
205a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
205b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
205c0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
205d0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
205e0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
205f0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
20600 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
20610 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
20620 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
20630 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
20640 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
20650 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
20660 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
20670 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
20680 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
20690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
206a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
206b0 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
206c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
206d0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
206e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
206f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20700 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
20710 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
20720 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
20730 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
20740 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
20750 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
20760 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
20770 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
20780 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
20790 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
207a0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
207b0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
207c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
207d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
207e0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
207f0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
20800 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
20810 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
20820 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
20830 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
20840 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
20850 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
20860 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
20870 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
20880 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
20890 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
208a0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
208b0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
208c0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
208d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
208e0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
208f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
20900 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
20910 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
20920 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
20930 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
20940 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
20950 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
20960 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
20970 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
20980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
20990 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
209a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
209b0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
209c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
209d0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
209e0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
209f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
20a00 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
20a10 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
20a20 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
20a30 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
20a40 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
20a50 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
20a60 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
20a70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
20a80 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
20a90 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
20aa0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
20ab0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
20ac0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
20ad0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
20ae0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
20af0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
20b00 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
20b10 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
20b20 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
20b30 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
20b40 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
20b50 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
20b60 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
20b70 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
20b80 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
20b90 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
20ba0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
20bb0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
20bc0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
20bd0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
20be0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
20bf0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
20c00 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
20c10 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
20c20 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
20c30 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
20c40 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
20c50 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
20c60 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
20c70 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
20c80 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
20c90 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
20ca0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
20cb0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
20cc0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
20cd0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
20ce0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
20cf0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
20d00 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
20d10 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
20d20 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
20d30 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
20d40 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
20d50 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
20d60 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
20d70 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
20d80 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
20d90 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
20da0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
20db0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
20dc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
20dd0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
20de0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
20df0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
20e00 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
20e10 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
20e20 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
20e30 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
20e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
20e50 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
20e60 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
20e70 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
20e80 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
20e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
20ea0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
20eb0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
20ec0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
20ed0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
20ee0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
20ef0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
20f00 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
20f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20f20 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
20f30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20f40 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
20f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20f60 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
20f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20f80 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
20f90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
20fa0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
20fb0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
20fc0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
20fd0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
20fe0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
20ff0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
21000 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21010 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
21020 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21030 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
21040 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21060 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
21070 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
21080 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
21090 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
210a0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
210b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
210c0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
210d0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
210e0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
210f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
21100 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
21110 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
21120 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
21130 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
21140 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
21150 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
21160 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
21170 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
21180 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
21190 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
211a0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
211b0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
211c0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
211d0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
211e0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
211f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
21200 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
21210 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
21220 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
21230 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
21240 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
21250 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21260 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
21270 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
21280 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
21290 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
212a0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
212b0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
212c0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
212d0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
212e0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
212f0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
21300 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
21310 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
21320 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
21330 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
21340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
21350 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
21360 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
21370 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
21380 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
21390 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
213a0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
213b0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
213c0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
213d0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
213e0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
213f0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
21400 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
21410 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
21420 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
21430 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
21440 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
21450 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
21460 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
21470 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
21480 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
21490 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
214a0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
214b0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
214c0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
214d0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
214e0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
214f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
21500 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
21510 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21520 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21530 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
21540 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
21550 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
21560 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
21570 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
21580 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
21590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
215a0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
215b0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
215c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
215d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
215e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
215f0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
21600 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
21610 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
21620 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
21630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21640 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
21650 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
21660 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
21670 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
21680 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
21690 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
216a0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
216b0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
216c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
216d0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
216e0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
216f0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
21700 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
21710 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
21720 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
21730 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21740 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
21750 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
21760 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
21770 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
21780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21790 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
217a0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
217b0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
217c0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
217d0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
217e0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
217f0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
21800 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
21810 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
21820 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
21830 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
21840 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
21850 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
21860 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
21870 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
21880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
21890 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
218a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
218b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
218c0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
218d0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
218e0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
218f0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
21900 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
21910 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
21920 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
21930 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
21940 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
21950 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
21960 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
21970 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
21980 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
21990 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
219a0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
219b0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
219c0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
219d0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
219e0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
219f0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
21a00 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
21a10 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
21a20 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
21a30 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
21a40 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
21a50 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
21a60 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
21a70 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
21a80 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
21a90 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
21aa0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
21ab0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
21ac0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
21ad0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
21ae0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
21af0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
21b00 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
21b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
21b20 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
21b30 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
21b40 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
21b50 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
21b60 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
21b70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
21b80 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
21b90 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
21ba0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
21bb0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
21bc0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
21bd0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
21be0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
21bf0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
21c00 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
21c10 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
21c20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
21c30 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
21c40 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
21c50 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
21c60 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
21c70 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
21c80 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
21c90 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
21ca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
21cb0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
21cc0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
21cd0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
21ce0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
21cf0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
21d00 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
21d10 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
21d20 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
21d30 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
21d40 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
21d50 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
21d60 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
21d70 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
21d80 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
21d90 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
21da0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
21db0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
21dc0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
21dd0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
21de0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
21df0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
21e00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
21e10 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
21e20 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
21e30 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
21e40 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
21e50 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
21e60 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
21e70 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
21e80 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
21e90 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
21ea0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21eb0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
21ec0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
21ed0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
21ee0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
21ef0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
21f00 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
21f10 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
21f20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
21f30 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
21f40 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
21f50 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
21f60 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
21f70 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
21f80 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
21f90 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
21fa0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
21fb0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
21fc0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
21fd0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
21fe0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
21ff0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
22000 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
22010 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
22020 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
22030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
22040 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
22050 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
22060 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
22070 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
22080 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
22090 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
220a0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
220b0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
220c0 69 74 20 77 61 73 20 72 65 71 75 69 72 65 64 0a  it was required.
220d0 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ** after sqlite3
220e0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
220f0 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20   anything other 
22100 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
22110 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  ] that.** [sqlit
22120 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20 63  e3_reset()] be c
22130 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e 79  alled before any
22140 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
22150 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
22160 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
22170 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65 20  ilure to invoke 
22180 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22190 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 77 6f  ] in this way wo
221a0 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  uld.** result in
221b0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
221c0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 20  SE] return from 
221d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
221e0 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76 65   But after.** ve
221f0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
22200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
22210 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73 71  egan calling [sq
22220 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 0a  lite3_reset()] .
22230 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
22240 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
22250 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 68 61  tance rather tha
22260 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
22270 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a 2a  ITE_MISUSE].  .*
22280 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
22290 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
222a0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
222b0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
222c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
222d0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
222e0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
222f0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
22300 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
22310 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
22320 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
22330 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
22340 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
22350 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
22360 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
22370 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22380 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
22390 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
223a0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
223b0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
223c0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
223d0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
223e0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
223f0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
22400 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
22410 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
22420 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
22430 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
22440 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
22450 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
22460 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
22470 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
22480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22490 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
224a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
224b0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
224c0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
224d0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
224e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
224f0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
22500 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
22510 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
22520 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
22530 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
22540 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
22550 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
22560 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
22570 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
22580 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
22590 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
225a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
225b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
225c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
225d0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
225e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
225f0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
22600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
22610 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
22620 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
22630 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
22640 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a  tatement] P..*/.
22650 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
22660 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
22670 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
22690 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
226a0 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
226b0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
226c0 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
226d0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
226e0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
226f0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
22700 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
22710 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
22720 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
22730 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
22740 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
22750 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
22760 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
22770 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
22780 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
22790 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
227a0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
227b0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
227c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
227d0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
227e0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
227f0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
22800 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
22810 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
22820 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
22830 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
22840 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
22850 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
22860 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
22870 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
22880 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
22890 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
228a0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
228b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
228c0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
228d0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
228e0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
228f0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
22900 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
22910 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
22920 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
22930 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
22940 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
22950 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
22960 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
22970 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
22980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22990 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
229a0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
229b0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
229c0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
229d0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
229e0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
229f0 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
22a00 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
22a10 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
22a20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
22a30 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
22a40 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
22a50 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
22a60 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
22a70 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
22a80 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
22a90 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22aa0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
22ab0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22ac0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
22ad0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
22ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
22af0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
22b00 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
22b10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22b20 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
22b30 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
22b40 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
22b50 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
22b60 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
22b70 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
22b80 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
22b90 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
22ba0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
22bb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22bc0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
22bd0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
22be0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
22bf0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
22c00 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
22c10 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
22c20 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
22c30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
22c40 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
22c50 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
22c60 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
22c70 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
22c80 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
22c90 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
22ca0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
22cb0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
22cc0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
22cd0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
22ce0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22cf0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
22d00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
22d10 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
22d20 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
22d30 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
22d40 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
22d50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22d60 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
22d70 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
22d80 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
22d90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
22da0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
22db0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22dc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
22dd0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
22de0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
22df0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
22e00 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
22e10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
22e20 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
22e30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
22e40 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
22e50 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
22e60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
22e70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22e80 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
22e90 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
22ea0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
22eb0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
22ec0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
22ed0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
22ee0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
22ef0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
22f00 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
22f10 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
22f20 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
22f30 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
22f40 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
22f50 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
22f60 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
22f70 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
22f80 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
22f90 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
22fa0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
22fb0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
22fc0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
22fd0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
22fe0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
22ff0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
23000 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
23010 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23020 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
23030 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
23040 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
23050 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
23060 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
23070 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
23080 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
23090 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
230a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
230b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
230c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
230d0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
230e0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
230f0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
23100 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
23110 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
23120 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
23130 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
23140 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
23150 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
23160 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
23170 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
23180 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
23190 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
231a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
231b0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
231c0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
231d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
231e0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
231f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
23200 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
23210 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
23220 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
23230 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
23240 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
23250 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
23260 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
23270 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
23280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23290 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
232a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
232b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
232c0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
232d0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
232e0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
232f0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23300 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
23310 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
23320 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
23330 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
23340 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
23350 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
23360 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
23370 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
23380 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
23390 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
233a0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
233b0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
233c0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
233d0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
233e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
233f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
23400 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
23410 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
23420 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
23430 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
23440 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
23450 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
23460 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
23470 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
23480 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
23490 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62  h BLOB is an arb
234a0 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
234b0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
234c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
234d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
234e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
234f0 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
23500 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
23510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23520 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
23530 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
23540 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
23550 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
23560 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  d of UTF-8..** ^
23570 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
23580 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
23590 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
235a0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  t..**.** ^The ob
235b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
235c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
235d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
235e0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
235f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
23600 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
23610 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23620 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
23630 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
23640 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
23650 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
23660 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
23670 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
23680 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
23690 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
236a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
236b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
236c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
236d0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
236e0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
236f0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
23700 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
23710 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
23720 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
23730 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
23740 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
23750 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
23760 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
23770 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
23780 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
23790 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
237a0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
237b0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
237c0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
237d0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
237e0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
237f0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
23800 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
23810 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
23820 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
23830 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
23840 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
23850 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
23860 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
23870 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
23880 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
23890 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
238a0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
238b0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
238c0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
238d0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
238e0 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
238f0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
23900 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
23910 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
23920 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
23930 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
23940 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
23950 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
23960 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
23970 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
23980 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
23990 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
239a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
239b0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
239c0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
239d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
239e0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
239f0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
23a00 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
23a10 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
23a20 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
23a30 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
23a40 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
23a50 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
23a60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
23a70 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
23a80 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
23a90 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
23aa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
23ab0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
23ac0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
23ad0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
23ae0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
23af0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
23b00 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
23b10 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
23b20 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
23b30 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
23b40 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
23b50 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
23b60 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
23b70 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
23b80 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
23b90 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
23ba0 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
23bb0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
23bc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
23bd0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
23be0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
23bf0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
23c00 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
23c10 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
23c20 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
23c30 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
23c40 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
23c50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
23c60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
23c70 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
23c80 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
23c90 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
23ca0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
23cb0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
23cc0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
23cd0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
23ce0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
23cf0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
23d00 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
23d10 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
23d20 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
23d30 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
23d40 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
23d50 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
23d60 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
23d70 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
23d80 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
23d90 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
23da0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
23db0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
23dc0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
23dd0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
23de0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
23df0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
23e00 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
23e10 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
23e20 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
23e30 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
23e40 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
23e50 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
23e60 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
23e70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  s..**.** ^Note t
23e80 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
23e90 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
23ea0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
23eb0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
23ec0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23ed0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
23ee0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23ef0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
23f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23f10 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
23f20 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e  nvalidated..** ^
23f30 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e  (Type conversion
23f40 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
23f50 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
23f60 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
23f70 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
23f80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23f90 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
23fa0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
23fb0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
23fc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
23fd0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
23fe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23ff0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
24000 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
24010 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
24020 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
24030 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
24040 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
24050 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
24060 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
24070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24080 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
24090 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
240a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
240b0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
240c0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
240d0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
240e0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
240f0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
24100 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
24110 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
24120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24130 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
24140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24150 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
24160 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
24170 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
24180 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
24190 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  </li>.** </ul>)^
241a0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
241b0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
241c0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
241d0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
241e0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
241f0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
24200 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
24210 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
24220 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
24230 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
24240 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
24250 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
24260 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
24270 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
24280 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
24290 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
242a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
242b0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
242c0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
242d0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
242e0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
242f0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
24300 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
24310 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
24320 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74 20 61  * ^(The safest a
24330 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
24340 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
24350 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
24360 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
24370 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
24380 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
24390 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
243a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
243b0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
243c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
243d0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
243e0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
243f0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
24400 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
24410 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
24420 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
24430 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24440 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
24450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24460 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
24470 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20  /ul>)^.**.** In 
24480 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
24490 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
244a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
244b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
244c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
244d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
244e0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
244f0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
24500 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
24510 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
24520 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
24530 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24540 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
24550 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
24560 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
24570 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
24580 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
24590 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
245a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
245b0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
245c0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
245d0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
245e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
245f0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
24600 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
24610 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24620 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
24630 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
24640 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
24650 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
24660 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
24670 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
24680 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
24690 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
246a0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
246b0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
246c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
246d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
246e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
246f0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
24700 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
24710 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
24720 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
24730 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
24740 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
24750 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
24760 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
24770 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
24780 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
24790 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
247a0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
247b0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
247c0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
247d0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
247e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
247f0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
24800 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
24810 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
24820 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
24830 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
24840 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
24850 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
24860 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
24870 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
24880 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
24890 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
248a0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
248b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
248c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
248d0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
248e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
248f0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
24900 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24910 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
24920 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24930 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
24940 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
24950 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24960 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24970 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
24980 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24990 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
249a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
249b0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
249c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
249d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
249e0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
249f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24a00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
24a10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
24a20 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
24a30 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
24a40 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
24a50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24a60 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
24a70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24a80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
24a90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24aa0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
24ab0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
24ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24ad0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
24ae0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
24af0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
24b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
24b10 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
24b20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
24b30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
24b40 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
24b50 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
24b60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24b70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
24b80 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
24b90 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
24ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24bb0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  t]..** ^If the s
24bc0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65  tatement was exe
24bd0 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
24be0 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  ly or not execut
24bf0 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a  ed at all, then.
24c00 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  ** SQLITE_OK is 
24c10 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65 78  returned. ^If ex
24c20 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
24c30 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
24c40 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
24c50 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
24c60 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
24c70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
24c80 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
24c90 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
24ca0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
24cb0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
24cc0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
24cd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24ce0 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72 74 75  .  ^If the virtu
24cf0 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
24d00 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
24d10 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
24d20 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
24d30 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
24d40 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
24d50 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
24d60 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
24d70 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
24d80 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65  t]..** ^Incomple
24d90 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
24da0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
24db0 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
24dc0 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65  anceled,.** depe
24dd0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72  nding on the cir
24de0 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20  cumstances, and 
24df0 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  the.** [error co
24e00 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
24e10 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
24e20 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  RT]..*/.int sqli
24e30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
24e40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
24e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24e60 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
24e70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
24e80 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
24e90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
24ea0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
24eb0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
24ec0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24ed0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
24ee0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
24ef0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
24f00 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
24f10 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
24f20 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
24f30 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
24f40 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
24f50 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
24f60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
24f70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24f80 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
24f90 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
24fa0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
24fb0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
24fc0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
24fd0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
24fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
24ff0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
25000 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
25010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
25020 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
25030 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
25040 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
25050 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
25060 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25070 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
25080 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
25090 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
250a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
250b0 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
250c0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
250d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
250e0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
250f0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
25100 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
25110 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
25120 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
25130 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
25140 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
25150 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25160 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
25170 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25180 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
25190 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
251a0 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
251b0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
251c0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
251d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
251e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
251f0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
25200 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
25210 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
25220 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
25230 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
25240 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
25250 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25260 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
25270 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
25280 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
25290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
252a0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
252b0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
252c0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
252d0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
252e0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
252f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
25300 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25310 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
25320 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
25330 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25340 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
25350 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f 20  *.** ^These two 
25360 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
25370 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
25380 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
25390 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
253a0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
253b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
253c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
253d0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
253e0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
253f0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
25400 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
25410 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
25420 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
25430 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
25440 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
25450 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
25460 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
25470 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
25480 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
25490 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
254a0 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
254b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
254c0 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
254d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
254e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
254f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
25500 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
25510 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25520 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
25530 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
25540 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
25550 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
25560 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
25570 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
25580 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
25590 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
255a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
255b0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
255c0 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
255d0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
255e0 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
255f0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  y..**.** The sec
25600 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25610 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
25630 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
25640 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
25650 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
25660 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
25670 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
25680 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
25690 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
256a0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
256b0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
256c0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
256d0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
256e0 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d  ers.  ^Any attem
256f0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
25700 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
25710 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
25720 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
25730 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e  LITE_ERROR] bein
25740 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
25750 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
25760 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
25770 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
25780 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
25790 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
257a0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
257b0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
257c0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
257d0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
257e0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
257f0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
25800 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
25810 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
25820 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
25830 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
25840 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
25850 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
25860 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
25870 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
25880 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
25890 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
258a0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
258b0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
258c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
258d0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
258e0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
258f0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
25900 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
25910 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
25920 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
25930 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
25940 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
25950 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
25960 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
25970 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
25980 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
25990 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
259a0 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
259b0 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
259c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
259d0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
259e0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
259f0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
25a00 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70  another.  ^An ap
25a10 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a  plication may.**
25a20 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
25a30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
25a40 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
25a50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
25a60 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
25a70 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
25a80 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
25a90 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
25aa0 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
25ab0 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
25ac0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
25ad0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
25ae0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
25af0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
25b00 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
25b10 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
25b20 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
25b30 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
25b40 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
25b50 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
25b60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
25b70 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
25b80 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
25b90 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
25ba0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
25bb0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
25bc0 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
25bd0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ANY]..**.** ^(Th
25be0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
25bf0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
25c00 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
25c10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
25c20 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
25c30 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
25c40 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
25c50 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
25c60 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
25c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
25c80 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
25c90 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
25ca0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
25cb0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
25cc0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
25cd0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
25ce0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
25cf0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25d00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
25d10 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
25d20 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
25d30 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
25d40 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
25d50 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
25d60 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
25d70 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
25d80 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
25d90 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
25da0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
25db0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
25dc0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
25dd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25de0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
25df0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
25e00 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
25e10 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
25e20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
25e30 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
25e40 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
25e50 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
25e60 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
25e70 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
25e80 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
25e90 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
25ea0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
25eb0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
25ec0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
25ed0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
25ee0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
25ef0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
25f00 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
25f10 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
25f20 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
25f30 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
25f40 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
25f50 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
25f60 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
25f70 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
25f80 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
25f90 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
25fa0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
25fb0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
25fc0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
25fd0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
25fe0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
25ff0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
26000 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
26010 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
26020 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
26030 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
26040 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26050 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
26060 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
26070 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
26080 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
26090 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
260a0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
260b0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
260c0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
260d0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
260e0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
260f0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
26100 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
26110 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
26120 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
26130 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
26140 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
26150 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
26160 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
26170 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
26180 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
26190 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
261a0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
261b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
261c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
261d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
261e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
261f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ed function with
26200 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76   a given name ov
26210 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62  errides all.** b
26220 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
26230 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  s in the same [d
26240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26250 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d  on] with the sam
26260 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73  e name..** ^Subs
26270 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69  equent applicati
26280 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26290 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
262a0 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72   name only overr
262b0 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70  ide .** prior ap
262c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
262d0 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  d functions that
262e0 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61   are an exact ma
262f0 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e  tch for the.** n
26300 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
26310 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65  ers and preferre
26320 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  d encoding..**.*
26330 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
26340 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26350 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
26360 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
26370 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
26380 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
26390 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
263a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
263b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
263c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
263d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
263e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
263f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
26400 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
26410 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
26420 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26430 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
26440 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
26450 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
26460 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
26470 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
26480 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
26490 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
264a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
264b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
264c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
264d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
264e0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
264f0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26500 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
26510 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
26520 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26530 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
26540 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
26550 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
26560 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
26570 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
26580 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
26590 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
265a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
265b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
265c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
265d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
265e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
265f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26600 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
26610 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
26620 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
26630 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
26640 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
26650 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
26660 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
26670 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
26680 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
26690 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
266a0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
266b0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
266c0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
266d0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
266e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
266f0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
26700 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
26710 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
26720 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
26730 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
26740 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26750 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
26760 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
26770 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
26780 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26790 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
267a0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
267b0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
267c0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
267d0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
267e0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
267f0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
26800 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
26810 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
26820 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
26830 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
26840 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
26850 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
26860 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
26870 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
26880 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
26890 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
268a0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
268b0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
268c0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
268d0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
268e0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
268f0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
26900 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
26910 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
26920 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
26930 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
26940 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
26950 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
26960 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
26970 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
26980 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26990 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
269a0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
269b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
269c0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
269d0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
269e0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
269f0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
26a00 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
26a10 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
26a20 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
26a30 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
26a40 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
26a50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
26a60 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
26a70 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
26a80 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
26a90 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
26aa0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
26ab0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
26ac0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
26ad0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
26ae0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
26af0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
26b00 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
26b10 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
26b20 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
26b30 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
26b40 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
26b50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
26b60 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
26b70 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
26b80 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
26b90 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
26ba0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
26bb0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
26bc0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
26bd0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
26be0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
26bf0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
26c00 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
26c10 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
26c20 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
26c30 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
26c40 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
26c50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26c60 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
26c70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26c80 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
26c90 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
26ca0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
26cb0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
26cc0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
26cd0 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
26ce0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
26cf0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
26d00 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
26d10 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
26d20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26d30 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
26d40 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
26d50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
26d60 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
26d70 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
26d80 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
26d90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
26da0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
26db0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
26dc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
26dd0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
26de0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
26df0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
26e00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26e10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
26e20 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
26e30 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
26e40 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
26e50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26e60 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
26e70 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
26e80 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
26e90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
26ea0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
26eb0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
26ec0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
26ed0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
26ee0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
26ef0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
26f00 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
26f10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26f20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
26f30 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
26f40 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
26f50 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
26f60 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
26f70 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
26f80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26f90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
26fa0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
26fb0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
26fc0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
26fd0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
26fe0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
26ff0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
27000 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27010 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
27020 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
27030 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
27040 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
27050 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
27060 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
27070 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
27080 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
27090 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
270a0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
270b0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
270c0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
270d0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
270e0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
270f0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
27100 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
27110 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
27120 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
27130 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
27140 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
27150 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
27160 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
27170 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
27180 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
27190 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
271a0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
271b0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
271c0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
271d0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
271e0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
271f0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
27200 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
27210 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
27220 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
27230 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
27240 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
27250 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
27260 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
27270 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
27280 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
27290 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
272a0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
272b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
272c0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
272d0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
272e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
272f0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
27300 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
27310 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
27320 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
27330 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
27340 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
27350 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
27360 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27370 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
27380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27390 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
273a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
273b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
273c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
273d0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
273e0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
273f0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
27400 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
27410 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
27420 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
27430 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
27440 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
27450 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27460 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
27470 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27480 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
27490 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
274a0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
274b0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
274c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
274d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
274e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
274f0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
27500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
27510 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
27520 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
27530 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
27540 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
27550 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
27560 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
27570 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
27580 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27590 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
275a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
275b0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
275c0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
275d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
275e0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
275f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27600 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
27610 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27620 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27630 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
27640 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27660 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
27670 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
27680 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
27690 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ntions of aggreg
276a0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
276b0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
276c0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
276d0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
276e0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
276f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
27700 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
27710 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27720 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
27730 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
27740 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
27750 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
27760 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
27770 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
27780 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
27790 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
277a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
277b0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
277c0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
277d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
277e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
277f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27800 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
27810 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
27820 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
27830 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
27840 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
27850 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
27860 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27870 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
27880 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
27890 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
278a0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
278b0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
278c0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
278d0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
278e0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
278f0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
27900 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
27910 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
27920 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
27930 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
27940 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
27950 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
27960 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
27970 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
27980 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
27990 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
279a0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
279b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
279c0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
279d0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
279e0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
279f0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
27a00 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
27a10 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
27a20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
27a30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
27a40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27a50 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
27a60 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
27a70 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
27a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
27a90 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
27aa0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
27ab0 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
27ac0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
27ad0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27ae0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
27af0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
27b00 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
27b10 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
27b20 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
27b30 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
27b40 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
27b50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
27b60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
27b70 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
27b80 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
27b90 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
27ba0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
27bb0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
27bc0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
27bd0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
27be0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
27bf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
27c00 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
27c10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27c20 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
27c30 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
27c40 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
27c50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
27c60 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
27c70 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
27c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
27c90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
27ca0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
27cb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
27cc0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
27cd0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
27ce0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
27cf0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
27d00 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
27d10 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
27d20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
27d30 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
27d40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
27d50 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
27d60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
27d70 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
27d80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
27d90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27da0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
27db0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
27dc0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
27dd0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
27de0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
27df0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27e00 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
27e10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
27e20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
27e30 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
27e40 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
27e50 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
27e60 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
27e70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
27e80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
27e90 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
27ea0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27eb0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
27ec0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
27ed0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
27ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
27ef0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
27f00 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
27f10 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
27f20 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
27f30 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
27f40 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
27f50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27f60 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
27f70 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
27f80 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
27f90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
27fa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27fb0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
27fc0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
27fd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27fe0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
27ff0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
28000 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
28010 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
28020 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
28030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28040 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
28050 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
28060 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28070 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
28080 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28090 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
280a0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
280b0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
280c0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
280d0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
280e0 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
280f0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
28100 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
28110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
28120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28130 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
28140 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
28150 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
28160 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
28170 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
28180 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
28190 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
281a0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
281b0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
281c0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
281d0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
281e0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
281f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
28200 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
28210 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
28220 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
28230 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
28240 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
28250 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
28260 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
28270 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
28280 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
28290 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
282a0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
282b0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
282c0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
282d0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
282e0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
282f0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
28300 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
28310 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28320 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
28330 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
28340 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
28350 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
28360 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
28370 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
28380 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
28390 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
283a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
283b0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
283c0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
283d0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
283e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
283f0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
28400 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
28410 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
28420 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28430 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
28440 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28450 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
28460 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
28470 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
28480 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
28490 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
284a0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
284b0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
284c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
284d0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
284e0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
284f0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
28500 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
28510 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
28520 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
28530 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
28540 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
28550 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
28560 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
28570 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
28580 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
28590 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
285a0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
285b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
285c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
285d0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
285e0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
285f0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
28600 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
28610 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
28620 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
28630 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
28640 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28650 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28660 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
28670 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
28680 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
28690 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
286a0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
286b0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
286c0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
286d0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
286e0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
286f0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
28700 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
28710 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
28720 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28730 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
28740 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
28750 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
28760 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
28770 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
28780 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
28790 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
287a0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
287b0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
287c0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
287d0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
287e0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
287f0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
28800 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
28810 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
28820 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
28830 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
28840 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
28850 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
28860 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
28870 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
28880 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
28890 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
288a0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
288b0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
288c0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
288d0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
288e0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
288f0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
28900 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
28910 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
28920 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
28930 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
28940 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
28950 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
28960 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
28970 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
28980 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
28990 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
289a0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
289b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
289c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
289d0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
289e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
289f0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
28a00 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
28a10 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
28a20 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
28a30 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
28a40 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
28a50 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
28a60 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
28a70 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
28a80 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
28a90 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
28aa0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
28ab0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
28ac0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
28ad0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
28ae0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
28af0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
28b00 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
28b10 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
28b20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
28b30 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
28b40 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
28b50 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
28b60 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
28b70 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28b80 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
28b90 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
28ba0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
28bb0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
28bc0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
28bd0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
28be0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
28bf0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
28c00 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
28c10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
28c20 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
28c30 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
28c40 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
28c50 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
28c60 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
28c70 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
28c80 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
28c90 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
28ca0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
28cb0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
28cc0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
28cd0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
28ce0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
28cf0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
28d00 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
28d10 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
28d20 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
28d30 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
28d40 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
28d50 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
28d60 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
28d70 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
28d80 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
28d90 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
28da0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
28db0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
28dc0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
28dd0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
28de0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
28df0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
28e00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28e10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
28e20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28e30 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
28e40 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
28e50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
28e60 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
28e70 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
28e80 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
28e90 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
28ea0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
28eb0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
28ec0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
28ed0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
28ee0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
28ef0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
28f00 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
28f10 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
28f20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
28f30 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
28f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28f50 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
28f60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
28f70 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
28f80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28f90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
28fa0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
28fb0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
28fc0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
28fd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28fe0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
28ff0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
29000 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
29010 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
29020 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29030 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
29040 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
29050 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
29060 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
29070 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29080 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
29090 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
290a0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
290b0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
290c0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
290d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
290e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
290f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29100 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
29110 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
29120 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
29130 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
29140 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29150 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
29160 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
29170 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
29180 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
29190 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
291a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
291b0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
291c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
291d0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
291e0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
291f0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
29200 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
29210 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
29220 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
29230 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
29240 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
29250 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
29260 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
29270 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
29280 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
29290 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
292a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
292b0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
292c0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
292d0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
292e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
292f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
29300 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
29310 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
29320 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
29330 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29340 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
29350 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
29360 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
29370 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29380 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
29390 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
293a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
293b0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
293c0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
293d0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
293e0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
293f0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
29400 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
29410 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
29420 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
29430 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29440 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29450 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
29460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29470 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
29480 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
29490 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
294a0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
294b0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
294c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
294d0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
294e0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
294f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29500 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
29510 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
29520 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
29530 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
29540 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
29550 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
29560 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
29570 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
29580 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
29590 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
295a0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
295b0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
295c0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
295d0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
295e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
295f0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
29600 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
29610 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
29620 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
29630 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
29640 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
29650 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
29660 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
29670 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
29680 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
29690 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
296a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
296b0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
296c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
296d0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
296e0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
296f0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
29700 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29710 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
29720 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
29730 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
29740 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
29750 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
29760 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
29770 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
29780 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
29790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
297a0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
297b0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
297c0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
297d0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
297e0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
297f0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
29800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29810 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
29820 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
29830 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
29840 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
29850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29860 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
29870 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
29880 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
29890 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
298a0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
298b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
298c0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
298d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
298e0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
298f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
29900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
29910 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
29920 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
29930 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
29940 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
29950 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
29960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
29970 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
29980 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
29990 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
299a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
299b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
299c0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
299d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
299e0 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
299f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
29a00 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
29a10 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
29a20 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
29a30 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
29a40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
29a50 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
29a60 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
29a70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29a80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
29a90 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
29aa0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
29ab0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
29ac0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
29ad0 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
29ae0 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
29af0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
29b00 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
29b10 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
29b20 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
29b30 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
29b40 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
29b50 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
29b60 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
29b70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29b80 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
29b90 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
29ba0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
29bb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
29bc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
29bd0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29be0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
29bf0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
29c00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
29c10 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
29c20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
29c30 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
29c40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
29c50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
29c60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
29c70 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
29c80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
29c90 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
29ca0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
29cb0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
29cc0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
29cd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
29ce0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
29cf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29d00 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
29d10 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
29d20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
29d30 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
29d40 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
29d50 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
29d60 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
29d70 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
29d80 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
29d90 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
29da0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
29db0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
29dc0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
29dd0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
29de0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
29df0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
29e00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
29e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
29e20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29e30 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
29e40 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
29e50 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
29e60 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
29e70 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
29e80 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
29e90 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
29ea0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
29eb0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
29ec0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
29ed0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
29ee0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
29ef0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
29f00 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
29f10 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
29f20 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
29f30 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
29f40 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
29f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
29f60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29f80 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29f90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
29fa0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
29fb0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
29fc0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
29fd0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
29fe0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
29ff0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
2a000 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
2a010 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
2a020 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2a030 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
2a040 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2a050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a060 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2a070 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2a080 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2a090 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2a0a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2a0b0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2a0c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a0d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2a0e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2a0f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2a100 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2a110 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2a120 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2a130 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
2a140 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2a150 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
2a160 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
2a170 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
2a180 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
2a190 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
2a1a0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
2a1b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a1c0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
2a1d0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
2a1e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2a1f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a200 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
2a210 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
2a220 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2a230 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a240 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
2a250 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
2a260 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
2a270 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
2a280 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
2a290 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
2a2a0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
2a2b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2a2c0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
2a2d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2a2e0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
2a2f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2a300 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a310 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
2a320 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
2a330 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2a340 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
2a350 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2a360 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
2a370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2a380 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2a390 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2a3a0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2a3b0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2a3c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2a3d0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
2a3e0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
2a3f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a400 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2a410 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a420 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
2a430 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a440 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
2a450 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2a460 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
2a470 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a480 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2a490 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a4a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a4b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2a4c0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
2a4d0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2a4e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2a4f0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
2a500 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2a510 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a520 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
2a530 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2a540 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a550 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
2a560 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2a570 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
2a580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2a590 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
2a5a0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2a5b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
2a5c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a5d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2a5e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2a5f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a600 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
2a610 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a620 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2a630 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2a640 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a650 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2a660 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a670 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2a680 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2a690 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2a6a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2a6b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a6c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2a6d0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2a6e0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2a6f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
2a700 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a710 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2a720 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a730 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
2a740 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a750 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2a760 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
2a770 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
2a780 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54  equences.**.** T
2a790 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2a7a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
2a7b0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
2a7c0 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
2a7d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2a7e0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
2a7f0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2a800 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2a810 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
2a820 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
2a830 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
2a840 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
2a850 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
2a860 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2a870 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
2a880 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2a890 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
2a8a0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2a8b0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2a8c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2a8d0 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  . ^In all cases.
2a8e0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
2a8f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
2a900 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2a910 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2a920 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2a930 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
2a940 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
2a950 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2a960 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2a970 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2a980 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
2a990 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
2a9a0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
2a9b0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
2a9c0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
2a9d0 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
2a9e0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
2a9f0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2aa00 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
2aa10 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
2aa20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54  respectively. ^T
2aa30 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75  he.** third argu
2aa40 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20  ment might also 
2aa50 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
2aa60 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  ] to indicate th
2aa70 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a  at the routine.*
2aa80 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65  * expects pointe
2aa90 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20  rs to be UTF-16 
2aaa0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e  strings in the n
2aab0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2aac0 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75  , or the.** argu
2aad0 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c  ment can be [SQL
2aae0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2aaf0 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65  D] if the.** the
2ab00 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
2ab10 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
2ab20 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
2ab30 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
2ab40 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
2ab50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2ab60 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
2ab70 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
2ab80 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
2ab90 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2aba0 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
2abb0 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73  ment.  ^If it is
2abc0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
2abd0 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
2abe0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
2abf0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
2ac00 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
2ac10 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
2ac20 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20  more)..** ^Each 
2ac30 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
2ac40 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75  tion supplied fu
2ac50 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
2ac60 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a  d, it is passed.
2ac70 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20  ** as its first 
2ac80 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79  parameter a copy
2ac90 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
2aca0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
2acb0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
2acc0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2acd0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20  _collation() or 
2ace0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2acf0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
2ad00 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69  .** ^The remaini
2ad10 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
2ad20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ad30 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
2ad40 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73   are two strings
2ad50 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73  ,.** each repres
2ad60 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67  ented by a (leng
2ad70 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61  th, data) pair a
2ad80 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68  nd encoded in th
2ad90 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68  e encoding.** th
2ada0 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73  at was passed as
2adb0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
2adc0 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  ent when the col
2add0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2ade0 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  was.** registere
2adf0 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  d.  The applicat
2ae00 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
2ae10 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
2ae20 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
2ae30 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
2ae40 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65   positive if the
2ae50 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
2ae60 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65   less than,.** e
2ae70 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
2ae80 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
2ae90 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  ond string. i.e.
2aea0 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
2aeb0 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NG2)..**.** ^The
2aec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2aed0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2aee0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
2aef0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2af00 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  on().** except t
2af10 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
2af20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
2af30 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
2af40 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
2af50 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65  collation.  ^The
2af60 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2af70 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
2af80 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
2af90 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
2afa0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
2afb0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2afc0 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
2afd0 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
2afe0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2aff0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
2b000 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20  ^Collations are 
2b010 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74  destroyed when t
2b020 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
2b030 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c  en by later call
2b040 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c  s to the.** coll
2b050 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
2b060 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
2b070 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2b080 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
2b090 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  osed.** using [s
2b0a0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
2b0b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b0c0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
2b0d0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
2b0e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
2b0f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2b100 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2b110 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b120 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
2b130 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2b140 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2b150 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2b160 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2b170 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2b180 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2b190 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
2b1a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b1b0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
2b1c0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2b1d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2b1e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2b1f0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2b200 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2b210 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2b220 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2b230 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2b240 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2b250 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2b260 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2b270 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2b280 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
2b290 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2b2a0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2b2b0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2b2c0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b2d0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b2e0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2b2f0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2b300 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2b310 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
2b320 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2b330 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2b340 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2b350 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2b360 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2b370 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2b380 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2b390 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2b3a0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2b3b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2b3c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2b3d0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
2b3e0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
2b3f0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
2b400 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
2b410 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2b420 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2b430 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2b440 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2b450 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2b460 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2b470 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2b480 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2b490 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2b4a0 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2b4b0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
2b4c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b4d0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
2b4e0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
2b4f0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2b500 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2b510 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
2b520 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
2b530 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
2b540 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
2b550 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
2b560 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
2b570 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
2b580 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2b590 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
2b5a0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
2b5b0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
2b5c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2b5d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
2b5e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
2b5f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2b600 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2b610 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
2b620 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
2b630 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2b640 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
2b650 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2b660 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2b670 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2b680 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
2b690 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2b6a0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2b6b0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
2b6c0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2b6d0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
2b6e0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2b6f0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
2b700 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2b710 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
2b720 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
2b730 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
2b740 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2b750 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2b760 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2b770 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2b780 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2b790 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b7a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2b7b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b7c0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2b7d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b7e0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
2b7f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2b800 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
2b810 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2b820 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2b830 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2b840 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2b850 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
2b860 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2b870 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
2b880 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
2b890 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2b8a0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2b8b0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
2b8c0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
2b8d0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
2b8e0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2b8f0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2b900 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2b910 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2b920 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2b930 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2b940 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2b950 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2b960 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2b970 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2b980 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2b990 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2b9a0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2b9b0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
2b9c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2b9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2b9e0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2b9f0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2ba00 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2ba10 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2ba20 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
2ba30 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
2ba40 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
2ba50 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
2ba60 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
2ba70 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
2ba80 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
2ba90 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
2baa0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
2bab0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
2bac0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
2bad0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
2bae0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2baf0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2bb00 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2bb10 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2bb20 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2bb30 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2bb40 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
2bb50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2bb60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2bb70 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2bb80 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2bb90 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2bba0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2bbb0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2bbc0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2bbd0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2bbe0 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
2bbf0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2bc00 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2bc10 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
2bc20 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
2bc30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
2bc40 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
2bc50 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2bc60 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2bc70 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2bc80 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2bc90 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
2bca0 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
2bcb0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2bcc0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2bcd0 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
2bce0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
2bcf0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
2bd00 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
2bd10 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2bd20 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2bd30 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
2bd40 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2bd50 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2bd60 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2bd70 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2bd80 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2bd90 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2bda0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2bdb0 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Time.**.** ^The
2bdc0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2bdd0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
2bde0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2bdf0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
2be00 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
2be10 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
2be20 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2be30 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2be40 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2be50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65 72  .** ^If the oper
2be60 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
2be70 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
2be80 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
2be90 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
2bea0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2beb0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2bec0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2bed0 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
2bee0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68  rest second. ^Th
2bef0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2bf00 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2bf10 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
2bf20 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
2bf30 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2bf40 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
2bf50 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
2bf60 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2bf70 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2bf80 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2bf90 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2bfa0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2bfb0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
2bfc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2bfd0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2bfe0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2bff0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
2c000 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
2c010 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
2c020 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
2c030 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
2c040 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
2c050 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
2c060 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
2c070 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
2c080 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
2c090 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
2c0a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
2c0b0 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
2c0c0 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
2c0d0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
2c0e0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
2c0f0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
2c100 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
2c110 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
2c120 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
2c130 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
2c140 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
2c150 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
2c160 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
2c170 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
2c180 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
2c190 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2c1a0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2c1b0 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
2c1c0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
2c1d0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
2c1e0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
2c1f0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
2c200 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
2c210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c220 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
2c230 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
2c240 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
2c250 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
2c260 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
2c270 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2c280 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
2c290 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
2c2a0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
2c2b0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
2c2c0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
2c2d0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
2c2e0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2c2f0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
2c300 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
2c310 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
2c320 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
2c330 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2c340 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2c350 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
2c360 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
2c370 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
2c380 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2c390 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2c3a0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
2c3b0 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
2c3c0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2c3d0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2c3e0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
2c3f0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
2c400 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
2c410 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
2c420 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
2c430 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2c440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
2c450 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
2c460 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
2c470 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
2c480 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
2c490 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
2c4a0 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
2c4b0 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
2c4c0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
2c4d0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
2c4e0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
2c4f0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
2c500 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2c510 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2c520 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
2c530 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
2c540 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2c550 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2c560 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2c570 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
2c580 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
2c590 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
2c5a0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
2c5b0 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
2c5c0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
2c5d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
2c5e0 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
2c5f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c600 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
2c610 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c620 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
2c630 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
2c640 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
2c650 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
2c660 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
2c670 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
2c680 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
2c690 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
2c6a0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
2c6b0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2c6c0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2c6d0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
2c6e0 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
2c6f0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
2c700 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2c710 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2c720 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2c730 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2c740 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2c750 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2c760 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2c770 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2c780 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
2c790 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
2c7a0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
2c7b0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
2c7c0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
2c7d0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
2c7e0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
2c7f0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
2c800 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
2c810 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
2c820 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
2c830 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
2c840 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
2c850 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2c860 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2c870 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2c880 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2c890 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2c8a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2c8b0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
2c8c0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
2c8d0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
2c8e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2c8f0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
2c900 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
2c910 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
2c920 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
2c930 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
2c940 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2c950 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2c960 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
2c970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2c980 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
2c990 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
2c9a0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2c9b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c9c0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
2c9d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2c9e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2c9f0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2ca00 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
2ca10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ca20 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68  t] belongs.  ^Th
2ca30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ca40 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
2ca50 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
2ca60 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
2ca70 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2ca80 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
2ca90 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
2caa0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2cab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2cac0 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
2cad0 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
2cae0 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
2caf0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
2cb00 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2cb10 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2cb20 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2cb30 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
2cb40 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2cb50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
2cb60 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
2cb70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2cb80 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
2cb90 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2cba0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65  ointer to the ne
2cbb0 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
2cbc0 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a  tement] after.**
2cbd0 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65   pStmt associate
2cbe0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
2cbf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cc00 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74   pDb.  ^If pStmt
2cc10 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
2cc20 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2cc30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2cc40 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
2cc50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc60 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
2cc70 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
2cc80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
2cc90 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72  .  ^If no prepar
2cca0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2ccb0 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
2ccc0 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
2ccd0 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
2cce0 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
2ccf0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2cd00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
2cd10 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
2cd20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
2cd30 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
2cd40 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
2cd50 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
2cd60 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
2cd70 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
2cd80 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
2cd90 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69  pointer..*/.sqli
2cda0 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
2cdb0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
2cdc0 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
2cdd0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2cde0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cdf0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
2ce00 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
2ce10 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
2ce20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2ce30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
2ce40 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2ce50 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2ce60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2ce70 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2ce80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ce90 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
2cea0 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
2ceb0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2cec0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2ced0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2cee0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2cef0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2cf00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2cf10 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2cf20 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
2cf30 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
2cf40 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2cf50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2cf60 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2cf70 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2cf80 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
2cf90 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
2cfa0 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
2cfb0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2cfc0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2cfd0 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
2cfe0 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
2cff0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d010 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2d020 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
2d030 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
2d040 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
2d050 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
2d060 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
2d070 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
2d080 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
2d090 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
2d0a0 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
2d0b0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
2d0c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
2d0d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2d0e0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
2d0f0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
2d100 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
2d110 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
2d120 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
2d130 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
2d140 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
2d150 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2d160 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2d170 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d180 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2d190 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2d1a0 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
2d1b0 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
2d1c0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
2d1d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2d1e0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2d1f0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2d200 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2d210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2d220 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
2d230 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
2d240 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2d250 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2d260 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2d270 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2d280 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2d290 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2d2a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d2b0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2d2c0 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
2d2d0 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
2d2e0 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
2d2f0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
2d300 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2d310 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2d320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d330 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2d340 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2d350 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2d360 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2d370 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2d380 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2d390 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
2d3a0 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
2d3b0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
2d3c0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
2d3d0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2d3e0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2d3f0 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
2d400 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
2d410 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
2d420 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
2d430 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
2d440 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
2d450 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
2d460 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
2d470 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
2d480 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
2d490 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
2d4a0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2d4b0 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2d4c0 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2d4d0 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2d4e0 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2d4f0 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2d500 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2d510 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2d520 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2d530 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
2d540 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
2d550 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2d560 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
2d570 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
2d580 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
2d590 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
2d5a0 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
2d5b0 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
2d5c0 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
2d5d0 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
2d5e0 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
2d5f0 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
2d600 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
2d610 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
2d620 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2d630 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2d640 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
2d650 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
2d660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2d670 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
2d680 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
2d690 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2d6a0 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
2d6b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2d6c0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
2d6d0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
2d6e0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
2d6f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
2d700 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
2d710 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
2d720 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
2d730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2d740 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
2d750 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2d760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d770 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2d780 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2d790 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2d7a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
2d7b0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2d7c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
2d7d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
2d7e0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2d7f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2d800 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
2d810 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2d820 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2d830 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
2d840 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2d850 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
2d860 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
2d870 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2d880 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2d890 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
2d8a0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2d8b0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2d8c0 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2d8d0 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2d8e0 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2d8f0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2d900 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
2d910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d920 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
2d930 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
2d940 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2d950 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
2d960 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
2d970 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
2d980 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
2d990 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2d9a0 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
2d9b0 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
2d9c0 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2d9d0 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
2d9e0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
2d9f0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
2da00 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
2da10 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
2da20 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2da30 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
2da40 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
2da50 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
2da60 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2da70 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
2da80 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
2da90 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
2daa0 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
2dab0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
2dac0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
2dad0 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
2dae0 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
2daf0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
2db00 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
2db10 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
2db20 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
2db30 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2db40 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2db50 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
2db60 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
2db70 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
2db80 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
2db90 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
2dba0 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
2dbb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
2dbc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
2dbd0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2dbe0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2dbf0 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
2dc00 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2dc10 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
2dc20 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
2dc30 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
2dc40 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
2dc50 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
2dc60 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
2dc70 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
2dc80 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
2dc90 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
2dca0 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
2dcb0 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
2dcc0 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
2dcd0 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
2dce0 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
2dcf0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
2dd00 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2dd10 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
2dd20 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2dd30 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2dd40 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2dd50 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2dd60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2dd70 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
2dd80 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
2dd90 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2dda0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2ddb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2ddc0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2ddd0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2dde0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2ddf0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2de00 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2de10 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
2de20 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
2de30 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2de40 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2de50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2de60 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2de70 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2de80 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2de90 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2dea0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2deb0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2dec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
2ded0 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
2dee0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
2def0 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
2df00 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
2df10 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
2df20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2df30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2df40 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
2df50 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2df60 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
2df70 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2df80 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
2df90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
2dfa0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
2dfb0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f  * interfaces..*/
2dfc0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2dfd0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2dfe0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2dff0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2e000 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2e010 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2e020 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2e030 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2e040 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2e050 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2e060 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
2e070 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
2e080 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
2e090 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
2e0a0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
2e0b0 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
2e0c0 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
2e0d0 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
2e0e0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
2e0f0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
2e100 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
2e110 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
2e120 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2e130 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
2e140 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
2e150 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
2e160 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
2e170 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2e180 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
2e190 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
2e1a0 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
2e1b0 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
2e1c0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
2e1d0 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
2e1e0 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
2e1f0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
2e200 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2e210 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
2e220 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
2e230 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2e240 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2e250 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2e260 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
2e270 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2e280 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2e290 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2e2a0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2e2b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2e2c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2e2d0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2e2e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2e2f0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2e300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e310 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2e320 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2e330 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2e340 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2e350 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2e360 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
2e370 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2e380 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2e390 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
2e3a0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
2e3b0 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
2e3c0 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
2e3d0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2e3e0 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
2e3f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
2e400 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
2e410 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
2e420 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
2e430 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
2e440 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2e450 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
2e460 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
2e470 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
2e480 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
2e490 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
2e4a0 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
2e4b0 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
2e4c0 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
2e4d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2e4e0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
2e4f0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
2e500 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
2e510 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
2e520 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
2e530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
2e540 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
2e550 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2e560 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
2e570 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
2e580 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
2e590 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2e5a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2e5b0 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
2e5c0 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
2e5d0 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
2e5e0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
2e5f0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
2e600 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
2e610 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
2e620 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
2e630 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
2e640 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2e650 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
2e660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2e670 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
2e680 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
2e690 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
2e6a0 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
2e6b0 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a  t requested..*/.
2e6c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
2e6d0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
2e6e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e6f0 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
2e700 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
2e710 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e720 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2e730 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61  () interface pla
2e740 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  ces a "soft" lim
2e750 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f  it.** on the amo
2e760 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
2e770 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
2e780 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
2e790 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69 6e  te..** ^If an in
2e7a0 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f  ternal allocatio
2e7b0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74  n is requested t
2e7c0 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  hat would exceed
2e7d0 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61   the.** soft hea
2e7e0 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65  p limit, [sqlite
2e7f0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2e800 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ()] is invoked o
2e810 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69  ne or.** more ti
2e820 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73  mes to free up s
2e830 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65  ome space before
2e840 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   the allocation 
2e850 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  is performed..**
2e860 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20 69  .** ^The limit i
2e870 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 20  s called "soft" 
2e880 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69  because if [sqli
2e890 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2e8a0 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20  ry()].** cannot 
2e8b0 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20  free sufficient 
2e8c0 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e  memory to preven
2e8d0 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d  t the limit from
2e8e0 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c   being exceeded,
2e8f0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  .** the memory i
2e900 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77  s allocated anyw
2e910 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65  ay and the curre
2e920 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  nt operation pro
2e930 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ceeds..**.** ^A 
2e940 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
2e950 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
2e960 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
2e970 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
2e980 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
2e990 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2e9a0 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
2e9b0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
2e9c0 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
2e9d0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  ed..** ^The defa
2e9e0 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
2e9f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2ea00 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
2ea10 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73 20   ^(SQLite makes 
2ea20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f  a best effort to
2ea30 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20   honor the soft 
2ea40 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42  heap limit..** B
2ea50 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68  ut if the soft h
2ea60 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74  eap limit cannot
2ea70 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65   be honored, exe
2ea80 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63  cution will.** c
2ea90 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20  ontinue without 
2eaa0 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63  error or notific
2eab0 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20 69  ation.)^  This i
2eac0 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20  s why the limit 
2ead0 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22  is.** called a "
2eae0 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74  soft" limit.  It
2eaf0 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
2eb00 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  y..**.** Prior t
2eb10 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
2eb20 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75   3.5.0, this rou
2eb30 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72  tine only constr
2eb40 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79  ained the memory
2eb50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  .** allocated by
2eb60 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
2eb70 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65   - the same thre
2eb80 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73  ad in which this
2eb90 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73   routine.** runs
2eba0 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  .  Beginning wit
2ebb0 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
2ebc0 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74   3.5.0, the soft
2ebd0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a   heap limit is.*
2ebe0 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c  * applied to all
2ebf0 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61   threads. The va
2ec00 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f  lue specified fo
2ec10 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2ec20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75  limit.** is an u
2ec30 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
2ec40 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61  e total memory a
2ec50 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c  llocation for al
2ec60 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a  l threads. In.**
2ec70 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
2ec80 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
2ec90 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
2eca0 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
2ecb0 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
2ecc0 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  al threads..*/.v
2ecd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
2ece0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
2ecf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ed00 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
2ed10 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
2ed20 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
2ed30 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2ed40 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2ed50 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2ed60 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2ed70 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2ed80 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2ed90 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2eda0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2edb0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2edc0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2edd0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2ede0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2edf0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
2ee00 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
2ee10 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
2ee20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ee30 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
2ee40 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
2ee50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2ee60 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
2ee70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2ee80 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
2ee90 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
2eea0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2eeb0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
2eec0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
2eed0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
2eee0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
2eef0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
2ef00 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
2ef10 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
2ef20 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
2ef30 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
2ef40 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
2ef50 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
2ef60 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
2ef70 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
2ef80 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
2ef90 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2efa0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2efb0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
2efc0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
2efd0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
2efe0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
2eff0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
2f000 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
2f010 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
2f020 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
2f030 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
2f040 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
2f050 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
2f060 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
2f070 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
2f080 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
2f090 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
2f0a0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2f0b0 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
2f0c0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
2f0d0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
2f0e0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
2f0f0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
2f100 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
2f110 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
2f120 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
2f130 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2f140 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2f150 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
2f160 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
2f170 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
2f180 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2f190 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
2f1a0 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
2f1b0 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
2f1c0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
2f1d0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
2f1e0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
2f1f0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
2f200 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
2f210 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f220 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f230 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
2f240 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
2f250 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
2f260 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2f270 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2f280 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
2f290 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
2f2a0 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
2f2b0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2f2c0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2f2d0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
2f2e0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
2f2f0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2f300 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
2f310 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
2f320 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
2f330 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2f340 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
2f350 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
2f360 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
2f370 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
2f380 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
2f390 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
2f3a0 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
2f3b0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
2f3c0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
2f3d0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
2f3e0 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
2f3f0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2f400 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
2f410 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
2f420 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
2f430 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
2f440 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
2f450 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2f460 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
2f470 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
2f480 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
2f490 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2f4a0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
2f4b0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
2f4c0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
2f4d0 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
2f4e0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2f4f0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2f500 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2f510 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2f520 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2f530 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2f540 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2f550 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2f560 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2f570 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2f580 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2f590 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2f5a0 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2f5b0 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2f5c0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2f5d0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2f5e0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
2f5f0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
2f600 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
2f610 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
2f620 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
2f630 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
2f640 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
2f650 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
2f660 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
2f670 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
2f680 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
2f690 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2f6a0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
2f6b0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2f6c0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
2f6d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f6e0 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
2f6f0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
2f700 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
2f710 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
2f720 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
2f730 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2f740 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2f750 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2f760 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2f770 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2f780 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2f790 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
2f7a0 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
2f7b0 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
2f7c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2f7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2f7e0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
2f7f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2f800 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
2f810 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2f820 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
2f830 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2f840 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
2f850 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
2f860 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
2f870 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
2f880 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
2f890 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
2f8a0 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
2f8b0 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
2f8c0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
2f8d0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
2f8e0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
2f8f0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
2f900 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
2f910 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
2f920 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
2f930 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2f940 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
2f950 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
2f960 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
2f970 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
2f980 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2f990 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
2f9a0 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
2f9b0 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
2f9c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2f9d0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2f9e0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
2f9f0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
2fa00 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
2fa10 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
2fa20 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2fa30 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
2fa40 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
2fa50 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
2fa60 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
2fa70 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
2fa80 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
2fa90 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2faa0 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
2fab0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2fac0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
2fad0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
2fae0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
2faf0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
2fb00 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
2fb10 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
2fb20 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
2fb30 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
2fb40 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
2fb50 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
2fb60 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
2fb70 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
2fb80 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
2fb90 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2fba0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2fbb0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2fbc0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2fbd0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2fbe0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
2fbf0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
2fc00 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
2fc10 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
2fc20 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2fc30 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
2fc40 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
2fc50 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
2fc60 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
2fc70 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
2fc80 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
2fc90 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2fca0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2fcb0 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
2fcc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
2fcd0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
2fce0 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
2fcf0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2fd00 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
2fd10 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
2fd20 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
2fd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
2fd40 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2fd50 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
2fd60 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
2fd70 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2fd80 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2fd90 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
2fda0 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
2fdb0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
2fdc0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
2fdd0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
2fde0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
2fdf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2fe00 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
2fe10 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
2fe20 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
2fe30 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
2fe40 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
2fe50 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
2fe60 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
2fe70 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
2fe80 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
2fe90 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
2fea0 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
2feb0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
2fec0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
2fed0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
2fee0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
2fef0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
2ff00 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
2ff10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2ff20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2ff30 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2ff40 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
2ff50 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
2ff60 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
2ff70 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
2ff80 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
2ff90 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
2ffa0 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
2ffb0 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
2ffc0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
2ffd0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
2ffe0 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
2fff0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
30000 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
30010 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
30020 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
30030 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
30040 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
30050 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
30060 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
30070 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
30080 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
30090 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
300a0 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
300b0 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
300c0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
300d0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
300e0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
300f0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
30100 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
30110 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
30120 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
30130 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
30140 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30150 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30160 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
30170 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
30180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30190 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
301a0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
301b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  s.**.** ^This AP
301c0 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64  I can be invoked
301d0 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72   at program star
301e0 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  tup in order to 
301f0 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20  register.** one 
30200 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c  or more statical
30210 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73  ly linked extens
30220 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ions that will b
30230 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74  e available.** t
30240 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62  o all new [datab
30250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
30260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
30270 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
30280 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
30290 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70  xtension entry p
302a0 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  oint.** in an ar
302b0 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74 61  ray that is obta
302c0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
302d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
302e0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  hat memory.** is
302f0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20   deallocated by 
30300 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
30310 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
30320 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  .)^.**.** ^This 
30330 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
30340 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
30350 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
30360 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
30370 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65  ally invoked whe
30380 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74  never a new [dat
30390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
303a0 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20 75  ].** is opened u
303b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
303c0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
303d0 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72  open16()],.** or
303e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
303f0 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69 63  2()]..** ^Duplic
30400 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
30410 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
30420 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
30430 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ine.** multiple 
30440 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
30450 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
30460 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e 41   harmless..** ^A
30470 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
30480 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
30490 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
304a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
304b0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
304c0 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28   (*xEntryPoint)(
304d0 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void));../*.** C
304e0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
304f0 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
30500 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
30510 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
30520 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72   disables all pr
30530 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
30540 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  red automatic.**
30550 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74 20   extensions. It 
30560 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
30570 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a  t of all prior.*
30580 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  * [sqlite3_auto_
30590 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c  extension()] cal
305a0 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ls.)^.**.** ^Thi
305b0 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
305c0 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78  les automatic ex
305d0 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
305e0 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64  threads..*/.void
305f0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
30600 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
30610 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
30620 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
30630 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
30640 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
30650 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
30660 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
30670 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
30680 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
30690 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
306a0 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
306b0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
306c0 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
306d0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
306e0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
306f0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
30700 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
30710 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
30720 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
30730 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
30740 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
30750 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
30760 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
30770 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
30780 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
30790 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
307a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
307b0 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
307c0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
307d0 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
307e0 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
307f0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
30800 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
30810 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
30820 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30830 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
30840 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30850 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
30860 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
30870 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
30880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30890 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
308a0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
308b0 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
308c0 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
308d0 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
308e0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
308f0 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
30900 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61   a a "virtual ta
30910 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a  ble module", .**
30920 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70   defines the imp
30930 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
30940 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
30950 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72  ].  .** This str
30960 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20  ucture consists 
30970 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
30980 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
30990 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75  ..**.** ^A virtu
309a0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20  al table module 
309b0 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69  is created by fi
309c0 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69  lling in a persi
309d0 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63  stent.** instanc
309e0 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
309f0 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20  ure and passing 
30a00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
30a10 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f  t instance.** to
30a20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30a30 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73  _module()] or [s
30a40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
30a50 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  dule_v2()]..** ^
30a60 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e  The registration
30a70 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75   remains valid u
30a80 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61  ntil it is repla
30a90 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65  ced by a differe
30aa0 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20  nt.** module or 
30ab0 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62  until the [datab
30ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
30ad0 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e  closes.  The con
30ae0 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20  tent.** of this 
30af0 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e  structure must n
30b00 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20  ot change while 
30b10 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64  it is registered
30b20 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74   with.** any dat
30b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30b40 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
30b50 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69  te3_module {.  i
30b60 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
30b70 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71  nt (*xCreate)(sq
30b80 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
30b90 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
30ba0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
30bb0 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
30bc0 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
30bd0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
30be0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
30bf0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e  *);.  int (*xCon
30c00 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20  nect)(sqlite3*, 
30c10 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
30c20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
30c30 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
30c40 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
30c50 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
30c60 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
30c70 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
30c80 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
30c90 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30ca0 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
30cb0 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74  ex_info*);.  int
30cc0 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
30cd0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30ce0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  Tab);.  int (*xD
30cf0 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
30d00 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
30d10 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
30d20 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
30d30 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  , sqlite3_vtab_c
30d40 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72  ursor **ppCursor
30d50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  );.  int (*xClos
30d60 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e)(sqlite3_vtab_
30d70 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
30d80 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74  (*xFilter)(sqlit
30d90 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
30da0 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e   int idxNum, con
30db0 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c  st char *idxStr,
30dc0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30dd0 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74   int argc, sqlit
30de0 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29  e3_value **argv)
30df0 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29  ;.  int (*xNext)
30e00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30e10 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
30e20 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
30e30 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
30e40 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
30e50 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30e60 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
30e70 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ext*, int);.  in
30e80 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69  t (*xRowid)(sqli
30e90 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30ea0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
30eb0 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20  *pRowid);.  int 
30ec0 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
30ed0 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
30ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
30ef0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
30f00 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67  *);.  int (*xBeg
30f10 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  in)(sqlite3_vtab
30f20 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
30f30 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
30f40 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
30f50 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
30f60 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30f70 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Tab);.  int (*xR
30f80 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33  ollback)(sqlite3
30f90 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
30fa0 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
30fb0 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  tion)(sqlite3_vt
30fc0 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e  ab *pVtab, int n
30fd0 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Arg, const char 
30fe0 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20  *zName,.        
30ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
31000 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73  oid (**pxFunc)(s
31010 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31020 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
31030 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20  e**),.          
31040 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
31050 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e  d **ppArg);.  in
31060 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
31070 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
31080 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
31090 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ew);.};../*.** C
310a0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
310b0 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20   Table Indexing 
310c0 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b  Information.** K
310d0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
310e0 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a  _index_info.**.*
310f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
31100 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
31110 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
31120 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
31130 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
31140 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
31150 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
31160 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
31170 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
31180 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
31190 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
311a0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
311b0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
311c0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
311d0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
311e0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
311f0 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
31200 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
31210 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
31220 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
31230 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
31240 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
31250 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
31260 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
31270 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
31280 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20  .** <pre>column 
31290 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a  OP expr</pre>.**
312a0 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20  .** where OP is 
312b0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
312c0 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29  &gt;, or &gt;=.)
312d0 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75  ^  ^(The particu
312e0 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a  lar operator is.
312f0 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f  ** stored in aCo
31300 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29 5e  nstraint[].op.)^
31310 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66    ^(The index of
31320 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
31330 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e  tored in.** aCon
31340 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
31350 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61  n.)^  ^(aConstra
31360 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
31370 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
31380 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
31390 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
313a0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
313b0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
313c0 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
313d0 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
313e0 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a  it cannot.)^.**.
313f0 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65  ** ^The optimize
31400 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
31410 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
31420 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
31430 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
31440 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
31450 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
31460 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
31470 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
31480 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
31490 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
314a0 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
314b0 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
314c0 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e  s possible..** ^
314d0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
314e0 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70  ] array only rep
314f0 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73  orts WHERE claus
31500 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 65  e terms that are
31510 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20  .** relevant to 
31520 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
31530 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
31540 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
31550 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  * ^Information a
31560 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
31570 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
31580 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
31590 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20  ..** ^Each term 
315a0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
315b0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
315c0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
315d0 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  use..**.** The [
315e0 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68  xBestIndex] meth
315f0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
31600 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
31610 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
31620 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
31630 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
31640 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e  s to xFilter.  ^
31650 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
31660 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
31670 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
31680 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
31690 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
316a0 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
316b0 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
316c0 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
316d0 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20   in argv.  ^(If 
316e0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
316f0 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
31700 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
31710 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
31720 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
31730 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
31740 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
31750 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
31760 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
31770 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e.)^.**.** ^The 
31780 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
31790 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
317a0 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
317b0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46   into the.** [xF
317c0 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a  ilter] method..*
317d0 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  * ^[sqlite3_free
317e0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
317f0 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
31800 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65  d only if.** nee
31810 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
31820 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   true..**.** ^Th
31830 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
31840 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
31850 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
31860 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
31870 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
31880 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
31890 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
318a0 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
318b0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
318c0 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
318d0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
318e0 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74  .** ^The estimat
318f0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
31900 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
31910 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
31920 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
31930 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
31940 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
31950 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
31960 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
31970 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
31980 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
31990 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
319a0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
319b0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
319c0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
319d0 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
319e0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
319f0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
31a00 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
31a10 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
31a20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
31a30 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
31a40 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
31a50 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
31a60 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
31a70 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
31a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
31a90 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
31aa0 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
31ab0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
31ac0 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
31ad0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
31ae0 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
31af0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
31b00 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
31b10 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
31b20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
31b30 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
31b40 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
31b50 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
31b60 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
31b70 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
31b80 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
31b90 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
31ba0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
31bb0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
31bc0 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
31bd0 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
31be0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
31bf0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
31c00 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
31c10 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
31c20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
31c30 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
31c40 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
31c50 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
31c60 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
31c70 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
31c80 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
31c90 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
31ca0 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
31cb0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
31cc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
31cd0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
31ce0 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
31cf0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
31d00 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
31d10 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
31d20 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
31d30 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
31d40 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
31d50 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
31d60 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
31d70 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
31d80 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
31d90 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
31da0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
31db0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
31dc0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
31dd0 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
31de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31df0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
31e00 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
31e10 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
31e20 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
31e30 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
31e40 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
31e50 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
31e60 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
31e70 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
31e80 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
31e90 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
31ea0 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
31eb0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
31ec0 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
31ed0 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
31ee0 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
31ef0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
31f00 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
31f10 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
31f20 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
31f30 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
31f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f50 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
31f60 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
31f70 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
31f80 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
31f90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31fa0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
31fb0 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
31fc0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
31fd0 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
31fe0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
31ff0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
32000 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
32010 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
32020 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
32030 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
32040 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
32050 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
32060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a  plementation.**.
32070 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
32080 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72  es are used to r
32090 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76  egister a new [v
320a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
320b0 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d  ule] name..** ^M
320c0 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
320d0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
320e0 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e  efore.** creatin
320f0 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  g a new [virtual
32100 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68   table] using th
32110 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66  e module and bef
32120 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70  ore using a.** p
32130 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74  reexisting [virt
32140 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74  ual table] for t
32150 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
32160 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d   ^The module nam
32170 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  e is registered 
32180 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
32190 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
321a0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
321b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
321c0 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  .  ^The name of 
321d0 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69  the module is gi
321e0 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73  ven by the .** s
321f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
32200 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
32210 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
32220 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ter to.** the im
32230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32240 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
32250 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54  le module].   ^T
32260 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72  he fourth.** par
32270 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
32280 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61  itrary client da
32290 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
322a0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
322b0 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78  h.** into the [x
322c0 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
322d0 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
322e0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
322f0 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68  ble module.** wh
32300 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c  en a new virtual
32310 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69   table is be bei
32320 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65  ng created or re
32330 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a  initialized..**.
32340 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32350 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
32360 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73  () interface has
32370 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74   a fifth paramet
32380 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
32390 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65   pointer to a de
323a0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
323b0 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e   pClientData.  ^
323c0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69  SQLite will.** i
323d0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
323e0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69  ctor function (i
323f0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
32400 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  ) when SQLite.**
32410 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73   no longer needs
32420 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
32430 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
32440 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
32450 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72  odule().** inter
32460 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
32470 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
32480 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
32490 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20   with a NULL.** 
324a0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69  destructor..*/.i
324b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
324c0 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
324d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
324e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
324f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
32500 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
32510 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
32520 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
32530 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
32540 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
32550 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
32560 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
32570 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
32580 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
32590 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
325a0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
325b0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
325c0 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e  Connect */.);.in
325d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
325e0 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
325f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
32600 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
32610 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
32620 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
32630 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
32640 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
32650 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
32660 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
32670 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
32680 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
32690 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
326a0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
326b0 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
326c0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
326d0 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
326e0 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
326f0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
32700 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
32710 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
32720 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
32730 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
32740 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
32750 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  tance Object.** 
32760 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
32770 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65  3_vtab.**.** Eve
32780 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
32790 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
327a0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
327b0 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74  subclass.** of t
327c0 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65  his object to de
327d0 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
327e0 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
327f0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
32800 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
32810 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
32820 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
32830 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
32840 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
32850 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
32860 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
32870 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
32880 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
32890 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
328a0 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
328b0 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
328c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
328d0 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61  *.** ^Virtual ta
328e0 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
328f0 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
32900 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
32910 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
32920 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32930 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
32940 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68   to zErrMsg.  Th
32950 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a  e method should.
32960 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61  ** take care tha
32970 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69  t any prior stri
32980 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61  ng is freed by a
32990 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
329a0 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69  3_free()].** pri
329b0 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
329c0 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
329d0 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72  zErrMsg.  ^After
329e0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
329f0 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
32a00 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
32a10 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
32a20 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
32a30 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
32a40 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
32a50 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
32a60 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
32a70 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
32a80 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  d..*/.struct sql
32a90 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
32aa0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
32ab0 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
32ac0 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
32ad0 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
32ae0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
32af0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
32b00 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f          /* NO LO
32b10 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63  NGER USED */.  c
32b20 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
32b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32b40 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
32b50 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
32b60 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
32b70 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
32b80 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
32b90 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
32ba0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
32bb0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
32bc0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
32bd0 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
32be0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
32bf0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
32c00 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
32c10 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a  able cursor}.**.
32c20 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
32c30 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
32c40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
32c50 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
32c60 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
32c70 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
32c80 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
32c90 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
32ca0 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
32cb0 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
32cc0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
32cd0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
32ce0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
32cf0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
32d00 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
32d10 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
32d20 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
32d30 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
32d40 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
32d50 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
32d60 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
32d70 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
32d80 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61  thod.  Cursors a
32d90 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
32da0 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
32db0 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
32dc0 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
32dd0 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
32de0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
32df0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
32e00 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
32e10 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
32e20 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
32e30 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
32e40 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
32e50 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
32e60 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
32e70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
32e80 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
32e90 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
32ea0 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
32eb0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
32ec0 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
32ed0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
32ee0 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
32ef0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
32f00 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
32f10 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
32f20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
32f30 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
32f40 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
32f50 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
32f60 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
32f70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32f80 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
32f90 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
32fa0 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  l Table.**.** ^T
32fb0 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
32fc0 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
32fd0 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72  ods of a.** [vir
32fe0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
32ff0 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74  e] call this int
33000 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63  erface.** to dec
33010 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
33020 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
33030 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
33040 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
33050 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
33060 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
33070 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33080 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
33090 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
330a0 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a  ar *zSQL);../*.*
330b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72  * CAPI3REF: Over
330c0 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20  load A Function 
330d0 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  For A Virtual Ta
330e0 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74  ble.**.** ^(Virt
330f0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
33100 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
33110 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
33120 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
33130 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46  ** using the [xF
33140 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74  indFunction] met
33150 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74  hod of the [virt
33160 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
33170 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62  ].  .** But glob
33180 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
33190 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
331a0 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
331b0 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
331c0 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  loaded.)^.**.** 
331d0 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73  ^(This API makes
331e0 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76   sure a global v
331f0 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63  ersion of a func
33200 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74  tion with a part
33210 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61  icular.** name a
33220 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  nd number of par
33230 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20  ameters exists. 
33240 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63   If no such func
33250 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62  tion exists.** b
33260 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69  efore this API i
33270 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20  s called, a new 
33280 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61  function is crea
33290 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70  ted.)^  ^The imp
332a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
332b0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
332c0 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
332d0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
332e0 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
332f0 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
33300 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
33310 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
33320 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
33330 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
33340 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
33350 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
33360 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
33370 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72  ded.** by a [vir
33380 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
33390 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
333a0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
333b0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
333c0 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
333d0 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
333e0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
333f0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
33400 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
33410 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
33420 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
33430 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
33440 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
33450 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
33460 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
33470 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
33480 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
33490 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
334a0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
334b0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
334c0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
334d0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
334e0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
334f0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
33500 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
33510 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
33520 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
33530 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
33540 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
33550 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
33560 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
33570 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
33580 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
33590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
335a0 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
335b0 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f  en BLOB.** KEYWO
335c0 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
335d0 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
335e0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
335f0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
33600 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
33610 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
33620 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
33630 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
33640 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
33650 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
33660 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20  ed..** ^Objects 
33670 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65  of this type are
33680 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
33690 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
336a0 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79  ].** and destroy
336b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
336c0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  lob_close()]..**
336d0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
336e0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
336f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
33700 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
33710 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
33720 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
33730 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
33740 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
33750 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
33760 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
33770 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33780 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
33790 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  e BLOB in bytes.
337a0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
337b0 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
337c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
337d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
337e0 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
337f0 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a  ncremental I/O.*
33800 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
33810 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b  rfaces opens a [
33820 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61  BLOB handle | ha
33830 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f  ndle] to the BLO
33840 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20  B located.** in 
33850 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e  row iRow, column
33860 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
33870 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
33880 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
33890 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
338a0 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f  ame BLOB that wo
338b0 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
338c0 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
338d0 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
338e0 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
338f0 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77  Table WHERE [row
33900 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  id] = iRow;.** <
33910 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  /pre>)^.**.** ^I
33920 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
33930 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
33940 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  o, then the BLOB
33950 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
33960 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65  ead.** and write
33970 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20   access. ^If it 
33980 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
33990 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
339a0 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20  read access..** 
339b0 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  ^It is not possi
339c0 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
339d0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
339e0 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72  t of an index or
339f0 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79   primary .** key
33a00 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49   for writing. ^I
33a10 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  f [foreign key c
33a20 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20  onstraints] are 
33a30 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a  enabled, it is .
33a40 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
33a50 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
33a60 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
33a70 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66   a [child key] f
33a80 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a  or writing..**.*
33a90 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
33aa0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
33ab0 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
33ac0 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
33ad0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
33ae0 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
33af0 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
33b00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
33b10 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66  at.** appears af
33b20 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
33b30 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  rd when the data
33b40 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
33b50 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
33b60 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61  ..** ^For the ma
33b70 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
33b80 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
33b90 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a  ame is "main"..*
33ba0 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  * ^For TEMP tabl
33bb0 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
33bc0 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
33bd0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
33be0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
33bf0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
33c00 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
33c10 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
33c20 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
33c30 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
33c40 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
33c50 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c  turned and *ppBl
33c60 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  ob is set.** to 
33c70 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  be a null pointe
33c80 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75  r.)^.** ^This fu
33c90 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
33ca0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33cb0 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
33cc0 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
33cd0 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
33ce0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
33cf0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33d00 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65  errmsg()] and re
33d10 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  lated.** functio
33d20 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  ns. ^Note that t
33d30 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61  he *ppBlob varia
33d40 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ble is always in
33d50 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a  itialized in a.*
33d60 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  * way that makes
33d70 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f   it safe to invo
33d80 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ke [sqlite3_blob
33d90 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70  _close()] on *pp
33da0 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65  Blob.** regardle
33db0 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
33dc0 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  s or failure of 
33dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
33de0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77  .** ^(If the row
33df0 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
33e00 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
33e10 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
33e20 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
33e30 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
33e40 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
33e50 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
33e60 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
33e70 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
33e80 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
33e90 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
33ea0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
33eb0 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
33ec0 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
33ed0 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
33ee0 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
33ef0 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a   is open on.)^.*
33f00 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  * ^Calls to [sql
33f10 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
33f20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
33f30 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
33f40 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
33f50 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
33f60 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
33f70 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
33f80 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67  ORT]..** ^(Chang
33f90 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  es written into 
33fa0 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20  a BLOB prior to 
33fb0 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e  the BLOB expirin
33fc0 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c  g are not.** rol
33fd0 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20  led back by the 
33fe0 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
33ff0 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68  e BLOB.  Such ch
34000 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74  anges will event
34010 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20  ually.** commit 
34020 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  if the transacti
34030 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  on continues to 
34040 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a  completion.)^.**
34050 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71  .** ^Use the [sq
34060 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
34070 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
34080 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
34090 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  ize of.** the op
340a0 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65  ened blob.  ^The
340b0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
340c0 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67  may not be chang
340d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e  ed by this.** in
340e0 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68  terface.  Use th
340f0 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63  e [UPDATE] SQL c
34100 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65  ommand to change
34110 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a   the size of a.*
34120 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54  * blob..**.** ^T
34130 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
34140 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64  _zeroblob()] and
34150 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34160 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74  _zeroblob()] int
34170 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74  erfaces.** and t
34180 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72  he built-in [zer
34190 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74  oblob] SQL funct
341a0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c  ion can be used,
341b0 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20   if desired,.** 
341c0 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70  to create an emp
341d0 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20  ty, zero-filled 
341e0 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f  blob in which to
341f0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75   read or write u
34200 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74  sing.** this int
34210 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f  erface..**.** To
34220 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63   avoid a resourc
34230 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70  e leak, every op
34240 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
34250 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c   should eventual
34260 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65  ly.** be release
34270 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
34280 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34290 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
342a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
342b0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
342c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
342d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
342e0 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
342f0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
34300 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
34310 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
34320 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
34330 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
34340 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
34350 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a  e A BLOB Handle.
34360 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e  **.** ^Closes an
34370 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
34380 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  le]..**.** ^Clos
34390 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
343a0 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
343b0 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
343c0 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
343d0 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
343e0 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
343f0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
34400 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
34410 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
34420 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61  nection is in [a
34430 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e  utocommit mode].
34440 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69 74  .** ^If any writ
34450 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
34460 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
34470 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
34480 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
34490 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
344a0 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
344b0 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f  fit..**.** ^(Clo
344c0 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66  sing the BLOB of
344d0 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63  ten forces the c
344e0 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f  hanges.** out to
344f0 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20   disk and so if 
34500 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f  any I/O errors o
34510 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20  ccur, they will 
34520 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20  likely occur.** 
34530 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
34540 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   the BLOB is clo
34550 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73  sed.  Any errors
34560 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
34570 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
34580 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
34590 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
345a0 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  value.)^.**.** ^
345b0 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f  (The BLOB is clo
345c0 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  sed unconditiona
345d0 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68  lly.  Even if th
345e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
345f0 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  ns.** an error c
34600 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ode, the BLOB is
34610 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e   still closed.)^
34620 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
34630 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
34640 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72  h a null pointer
34650 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64 20   (such as would 
34660 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  be returned.** b
34670 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c 20  y a failed call 
34680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
34690 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 68  _open()]) is a h
346a0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
346b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
346c0 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
346d0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
346e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
346f0 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e  n The Size Of An
34700 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a   Open BLOB.**.**
34710 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73 69   ^Returns the si
34720 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74  ze in bytes of t
34730 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62  he BLOB accessib
34740 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73  le via the .** s
34750 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e  uccessfully open
34760 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
34770 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   in its only arg
34780 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20  ument.  ^The.** 
34790 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62  incremental blob
347a0 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61   I/O routines ca
347b0 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f  n only read or o
347c0 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73 74  verwriting exist
347d0 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74  ing.** blob cont
347e0 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74  ent; they cannot
347f0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
34800 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   of a blob..**.*
34810 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
34820 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34830 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
34840 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
34850 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
34860 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34870 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34880 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34890 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
348a0 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
348b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
348c0 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
348d0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
348e0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
348f0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34900 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34910 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
34920 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34930 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
34940 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lob_bytes(sqlite
34950 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
34960 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64  * CAPI3REF: Read
34970 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
34980 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
34990 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
349a0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ction is used to
349b0 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20   read data from 
349c0 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  an open [BLOB ha
349d0 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20  ndle] into a.** 
349e0 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20  caller-supplied 
349f0 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20  buffer. N bytes 
34a00 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
34a10 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a  ed into buffer Z
34a20 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  .** from the ope
34a30 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
34a40 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
34a50 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  et.)^.**.** ^If 
34a60 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
34a70 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79  s less than N by
34a80 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
34a90 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a   of the BLOB,.**
34aa0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
34ab0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
34ac0 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
34ad0 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66 73    ^If N or iOffs
34ae0 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68  et is.** less th
34af0 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45  an zero, [SQLITE
34b00 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
34b10 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
34b20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65  is read..** ^The
34b30 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f   size of the blo
34b40 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  b (and hence the
34b50 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
34b60 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
34b70 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
34b80 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
34b90 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34ba0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
34bb0 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
34bc0 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20  to read from an 
34bd0 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
34be0 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
34bf0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
34c00 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
34c10 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  RT]..**.** ^(On 
34c20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33  success, sqlite3
34c30 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65 74  _blob_read() ret
34c40 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
34c50 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
34c60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
34c70 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
34c80 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
34c90 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  urned.)^.**.** T
34ca0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
34cb0 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
34cc0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
34cd0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
34ce0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
34cf0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
34d00 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
34d10 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
34d20 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
34d30 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
34d40 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
34d50 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
34d60 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
34d70 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
34d80 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
34d90 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
34da0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
34db0 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
34dc0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
34dd0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
34de0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
34df0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71  te3_blob_read(sq
34e00 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f  lite3_blob *, vo
34e10 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e  id *Z, int N, in
34e20 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
34e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69  ** CAPI3REF: Wri
34e40 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42  te Data Into A B
34e50 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
34e60 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
34e70 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
34e80 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74  o write data int
34e90 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  o an open [BLOB 
34ea0 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a  handle] from a.*
34eb0 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65  * caller-supplie
34ec0 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79 74  d buffer. ^N byt
34ed0 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
34ee0 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62  opied from the b
34ef0 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20  uffer Z.** into 
34f00 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
34f10 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
34f20 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
34f30 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68   ^If the [BLOB h
34f40 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
34f50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
34f60 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e  ent was not open
34f70 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e  ed for.** writin
34f80 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
34f90 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
34fa0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
34fb0 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68  was zero),.** th
34fc0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
34fd0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  rns [SQLITE_READ
34fe0 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ONLY]..**.** ^Th
34ff0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
35000 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
35010 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
35020 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e  BLOB; it is.** n
35030 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
35040 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
35050 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67   of a BLOB using
35060 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49   this API..** ^I
35070 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
35080 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
35090 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
350a0 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
350b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
350c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
350d0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
350e0 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a  tten.  ^If N is.
350f0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
35100 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
35110 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
35120 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
35130 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65  ten..** The size
35140 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e   of the BLOB (an
35150 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
35160 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
35170 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
35180 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
35190 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
351a0 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
351b0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
351c0 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
351d0 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
351e0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
351f0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
35200 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
35210 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
35220 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42  ^Writes to the B
35230 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65  LOB that occurre
35240 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  d.** before the 
35250 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78  [BLOB handle] ex
35260 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f  pired are not ro
35270 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
35280 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  .** expiration o
35290 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68  f the handle, th
352a0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
352b0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67  hose changes mig
352c0 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  ht.** have been 
352d0 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
352e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
352f0 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c  t expired the BL
35300 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20  OB handle.** or 
35310 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e  by other indepen
35320 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e  dent statements.
35330 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
35340 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ess, sqlite3_blo
35350 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72 6e  b_write() return
35360 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  s SQLITE_OK..** 
35370 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b  Otherwise, an  [
35380 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
35390 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
353a0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
353b0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69  ned.)^.**.** Thi
353c0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
353d0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
353e0 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
353f0 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
35400 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
35410 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
35420 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
35430 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
35440 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
35450 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
35460 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
35470 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
35480 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
35490 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
354a0 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
354b0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
354c0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
354d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
354e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
354f0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
35500 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35510 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69  _blob_write(sqli
35520 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73  te3_blob *, cons
35530 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  t void *z, int n
35540 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
35550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35560 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79   Virtual File Sy
35570 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a  stem Objects.**.
35580 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c  ** A virtual fil
35590 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73  esystem (VFS) is
355a0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
355b0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74  ] object.** that
355c0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20   SQLite uses to 
355d0 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68  interact.** with
355e0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
355f0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35600 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62  .  Most SQLite b
35610 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20  uilds come with 
35620 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61  a.** single defa
35630 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20  ult VFS that is 
35640 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
35650 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65  the host compute
35660 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20  r..** New VFSes 
35670 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
35680 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56  d and existing V
35690 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65  FSes can be unre
356a0 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65  gistered..** The
356b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72   following inter
356c0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
356d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
356e0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
356f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35700 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35710 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73   a VFS given its
35720 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73   name..** ^Names
35730 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74   are case sensit
35740 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61  ive..** ^Names a
35750 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
35760 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
35770 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20 69  ..** ^If there i
35780 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55  s no match, a NU
35790 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
357a0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a  turned..** ^If z
357b0 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  VfsName is NULL 
357c0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
357d0 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
357e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53  ..**.** ^New VFS
357f0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
35800 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
35810 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a  fs_register()..*
35820 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53 20  * ^Each new VFS 
35830 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
35840 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
35850 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
35860 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d  set..** ^The sam
35870 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67  e VFS can be reg
35880 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
35890 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69   times without i
358a0 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61  njury..** ^To ma
358b0 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56  ke an existing V
358c0 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61  FS into the defa
358d0 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65  ult VFS, registe
358e0 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69  r it again.** wi
358f0 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  th the makeDflt 
35900 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77  flag set.  If tw
35910 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65  o different VFSe
35920 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61  s with the.** sa
35930 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69  me name are regi
35940 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61  stered, the beha
35950 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
35960 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20  d.  If a.** VFS 
35970 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
35980 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69  th a name that i
35990 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
359a0 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68  ty string,.** th
359b0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
359c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
359d0 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72 20  .** ^Unregister 
359e0 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73  a VFS with the s
359f0 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
35a00 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63  ister() interfac
35a10 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 64  e..** ^(If the d
35a20 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
35a30 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
35a40 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
35a50 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
35a60 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
35a70 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
35a80 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29 5e   is arbitrary.)^
35a90 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20  .*/.sqlite3_vfs 
35aa0 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  *sqlite3_vfs_fin
35ab0 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56  d(const char *zV
35ac0 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c  fsName);.int sql
35ad0 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
35ae0 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  r(sqlite3_vfs*, 
35af0 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69  int makeDflt);.i
35b00 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  nt sqlite3_vfs_u
35b10 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  nregister(sqlite
35b20 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  3_vfs*);../*.** 
35b30 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65  CAPI3REF: Mutexe
35b40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  s.**.** The SQLi
35b50 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
35b60 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  se routines for 
35b70 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72  thread.** synchr
35b80 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67  onization. Thoug
35b90 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e  h they are inten
35ba0 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  ded for internal
35bb0 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
35bc0 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e  e, code that lin
35bd0 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
35be0 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65  e is.** permitte
35bf0 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20  d to use any of 
35c00 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
35c10 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
35c20 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e   source code con
35c30 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69  tains multiple i
35c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
35c50 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78  * of these mutex
35c60 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61   routines.  An a
35c70 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65  ppropriate imple
35c80 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
35c90 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74  selected automat
35ca0 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c  ically at compil
35cb0 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20 66  e-time.  ^(The f
35cc0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c  ollowing.** impl
35cd0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20  ementations are 
35ce0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35cf0 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a   SQLite core:.**
35d00 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
35d10 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
35d20 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  OS2.** <li>   SQ
35d30 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
35d40 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  AD.** <li>   SQL
35d50 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a  ITE_MUTEX_W32.**
35d60 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
35d70 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75  UTEX_NOOP.** </u
35d80 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  l>)^.**.** ^The 
35d90 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
35da0 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  P implementation
35db0 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75   is a set of rou
35dc0 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  tines.** that do
35dd0 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
35de0 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
35df0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
35e00 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72  .** a single-thr
35e10 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
35e20 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  n.  ^The SQLITE_
35e30 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
35e40 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
35e50 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
35e60 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
35e70 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
35e80 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
35e90 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69  use on OS/2, Uni
35ea0 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a  x, and Windows..
35eb0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
35ec0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
35ed0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
35ee0 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
35ef0 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
35f00 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
35f10 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
35f20 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
35f30 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
35f40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
35f50 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
35f60 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
35f70 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
35f80 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
35f90 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
35fa0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
35fb0 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
35fc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
35fd0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
35fe0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
35ff0 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
36000 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
36010 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
36020 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
36030 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
36040 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
36050 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
36060 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e  _initialize().)^
36070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36080 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36090 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61  ) routine alloca
360a0 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74  tes a new.** mut
360b0 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ex and returns a
360c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
360d0 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ^If it returns N
360e0 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e  ULL.** that mean
360f0 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63  s that a mutex c
36100 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f  ould not be allo
36110 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a  cated.  ^SQLite.
36120 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69  ** will unwind i
36130 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74  ts stack and ret
36140 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  urn an error.  ^
36150 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  (The argument.**
36160 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
36170 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
36180 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
36190 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
361a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
361b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
361c0 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
361d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
361e0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
361f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36200 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
36210 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
36220 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
36230 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36240 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
36250 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36260 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
36270 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36280 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
36290 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
362a0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
362b0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
362c0 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63  ^The first two c
362d0 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54 45  onstants (SQLITE
362e0 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20  _MUTEX_FAST and 
362f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36300 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73 65  URSIVE).** cause
36310 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
36320 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65  lloc() to create
36330 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e  .** a new mutex.
36340 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65 78    ^The new mutex
36350 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68   is recursive wh
36360 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
36370 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20  RECURSIVE.** is 
36380 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63  used but not nec
36390 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e  essarily so when
363a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
363b0 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54  ST is used..** T
363c0 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  he mutex impleme
363d0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
363e0 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20   need to make a 
363f0 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
36400 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55  etween SQLITE_MU
36410 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e  TEX_RECURSIVE an
36420 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  d SQLITE_MUTEX_F
36430 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a  AST if it does.*
36440 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20  * not want to.  
36450 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c  ^SQLite will onl
36460 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
36470 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
36480 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
36490 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
364a0 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65 72  e.  ^If a faster
364b0 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
364c0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
364d0 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
364e0 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
364f0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
36500 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
36510 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
36520 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
36530 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
36540 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
36550 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61 6c  ** ^The other al
36560 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73  lowed parameters
36570 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
36580 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68  x_alloc() (anyth
36590 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61  ing other.** tha
365a0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  n SQLITE_MUTEX_F
365b0 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AST and SQLITE_M
365c0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
365d0 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61  each return.** a
365e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
365f0 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67  atic preexisting
36600 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73 74   mutex.  ^Six st
36610 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
36620 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20  .** used by the 
36630 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20  current version 
36640 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75  of SQLite.  Futu
36650 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
36660 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64  QLite.** may add
36670 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
36680 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61  ic mutexes.  Sta
36690 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20  tic mutexes are 
366a0 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
366b0 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  use by SQLite on
366c0 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ly.  Application
366d0 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
366e0 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  e mutexes should
366f0 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65  .** use only the
36700 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
36710 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
36720 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f  ITE_MUTEX_FAST o
36730 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  r.** SQLITE_MUTE
36740 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a  X_RECURSIVE..**.
36750 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69 66  ** ^Note that if
36760 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
36770 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
36780 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
36790 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
367a0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
367b0 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
367c0 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
367d0 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
367e0 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
367f0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
36800 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20 74  all.  ^But for t
36810 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74  he static.** mut
36820 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
36830 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
36840 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
36850 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
36860 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
36870 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
36880 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
36890 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
368a0 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
368b0 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
368c0 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ed dynamic mutex
368d0 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63 61  .  ^SQLite is ca
368e0 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
368f0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
36900 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
36910 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54  it allocates.  T
36920 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
36930 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69  es must not be i
36940 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68  n.** use when th
36950 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  ey are deallocat
36960 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20  ed.  Attempting 
36970 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
36980 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
36990 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
369a0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20  ined behavior.  
369b0 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65  ^SQLite never de
369c0 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73  allocates.** a s
369d0 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a  tatic mutex..**.
369e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
369f0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e  mutex_enter() an
36a00 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
36a10 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61  try() routines a
36a20 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74  ttempt.** to ent
36a30 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49 66  er a mutex.  ^If
36a40 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
36a50 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69  is already withi
36a60 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20  n the mutex,.** 
36a70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
36a80 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b  ter() will block
36a90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
36aa0 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65  ex_try() will re
36ab0 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42  turn.** SQLITE_B
36ac0 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  USY.  ^The sqlit
36ad0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69  e3_mutex_try() i
36ae0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36af0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20   [SQLITE_OK].** 
36b00 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20  upon successful 
36b10 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78 65  entry.  ^(Mutexe
36b20 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
36b30 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
36b40 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65  RECURSIVE can be
36b50 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c   entered multipl
36b60 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73  e times by the s
36b70 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  ame thread..** I
36b80 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65  n such cases the
36b90 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20  ,.** mutex must 
36ba0 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75  be exited an equ
36bb0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  al number of tim
36bc0 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65  es before anothe
36bd0 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20  r thread.** can 
36be0 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20 74  enter.)^  ^(If t
36bf0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
36c00 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
36c10 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
36c20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
36c30 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
36c40 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
36c50 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ed..** SQLite wi
36c60 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
36c70 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
36c80 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
36c90 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a   of mutexes.)^.*
36ca0 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74  *.** ^(Some syst
36cb0 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ems (for example
36cc0 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f  , Windows 95) do
36cd0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
36ce0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d   operation.** im
36cf0 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c  plemented by sql
36d00 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
36d10 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
36d20 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
36d30 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c  ex_try().** will
36d40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
36d50 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65  QLITE_BUSY.  The
36d60 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
36d70 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73  y ever uses.** s
36d80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
36d90 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a  () as an optimiz
36da0 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73  ation so this is
36db0 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61   acceptable beha
36dc0 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  vior.)^.**.** ^T
36dd0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
36de0 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
36df0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
36e00 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
36e10 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
36e20 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36e30 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76 69  .   ^(The behavi
36e40 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
36e50 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ed if the mutex 
36e60 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
36e70 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a   entered by the.
36e80 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  ** calling threa
36e90 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72  d or is not curr
36ea0 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e  ently allocated.
36eb0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
36ec0 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72   never do either
36ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
36ee0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
36ef0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
36f00 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  r(), sqlite3_mut
36f10 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20  ex_try(), or.** 
36f20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
36f30 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  ave() is a NULL 
36f40 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c  pointer, then al
36f50 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  l three routines
36f60 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f  .** behave as no
36f70 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  -ops..**.** See 
36f80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
36f90 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
36fa0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36fb0 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
36fc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
36fd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
36fe0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
36ff0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
37000 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
37010 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
37020 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
37030 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
37040 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
37050 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37060 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
37070 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
37080 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
37090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
370a0 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  ex Methods Objec
370b0 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
370c0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
370d0 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68  cture defines th
370e0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74  e low-level rout
370f0 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ines.** used to 
37100 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65  allocate and use
37110 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20   mutexes..**.** 
37120 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66  Usually, the def
37130 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65  ault mutex imple
37140 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69  mentations provi
37150 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72  ded by SQLite ar
37160 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c  e.** sufficient,
37170 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65   however the use
37180 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e  r has the option
37190 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67   of substituting
371a0 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70   a custom.** imp
371b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  lementation for 
371c0 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c  specialized depl
371d0 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65  oyments or syste
371e0 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c  ms for which SQL
371f0 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
37200 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62  provide a suitab
37210 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37220 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c  n. In this case,
37230 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65   the user.** cre
37240 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74  ates and populat
37250 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  es an instance o
37260 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
37270 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73   to pass.** to s
37280 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
37290 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b  along with the [
372a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
372b0 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  TEX] option..** 
372c0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e  Additionally, an
372d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
372e0 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e 20  s structure can 
372f0 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a  be used as an.**
37300 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c 65   output variable
37310 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74   when querying t
37320 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68  he system for th
37330 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a  e current mutex.
37340 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
37350 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  n, using the [SQ
37360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
37370 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  UTEX] option..**
37380 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49  .** ^The xMutexI
37390 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e  nit method defin
373a0 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
373b0 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ture is invoked 
373c0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79  as.** part of sy
373d0 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74  stem initializat
373e0 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74  ion by the sqlit
373f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
37400 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  function..** ^Th
37410 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75  e xMutexInit rou
37420 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20 62 79  tine is calle by
37430 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c 79 20   SQLite exactly 
37440 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a  once for each.**
37450 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
37460 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  to [sqlite3_init
37470 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ialize()]..**.**
37480 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20   ^The xMutexEnd 
37490 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62  method defined b
374a0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
374b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a   is invoked as.*
374c0 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d  * part of system
374d0 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65   shutdown by the
374e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
374f0 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  n() function. Th
37500 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
37510 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68  ion of this meth
37520 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20 74  od is expected t
37530 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75  o release all ou
37540 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73  tstanding.** res
37550 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20  ources obtained 
37560 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74  by the mutex met
37570 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hods implementat
37580 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a  ion, especially.
37590 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65  ** those obtaine
375a0 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 49  d by the xMutexI
375b0 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68  nit method.  ^Th
375c0 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a  e xMutexEnd().**
375d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
375e0 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
375f0 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c  ce for each call
37600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   to [sqlite3_shu
37610 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
37620 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  ^(The remaining 
37630 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65  seven methods de
37640 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
37650 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41  ructure (xMutexA
37660 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46  lloc,.** xMutexF
37670 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72  ree, xMutexEnter
37680 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75  , xMutexTry, xMu
37690 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78  texLeave, xMutex
376a0 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74  Held and.** xMut
376b0 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65  exNotheld) imple
376c0 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ment the followi
376d0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72  ng interfaces (r
376e0 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a  espectively):.**
376f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
37700 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37710 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69  ex_alloc()] </li
37720 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
37730 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
37740 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
37750 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37760 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c  tex_enter()] </l
37770 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37780 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
37790 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
377a0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
377b0 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c  tex_leave()] </l
377c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
377d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
377e0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  d()] </li>.**   
377f0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37800 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20  utex_notheld()] 
37810 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  </li>.** </ul>)^
37820 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20  .**.** The only 
37830 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68  difference is th
37840 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71  at the public sq
37850 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69  lite3_XXX functi
37860 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a  ons enumerated.*
37870 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79  * above silently
37880 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f   ignore any invo
37890 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73  cations that pas
378a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
378b0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
378c0 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e   valid mutex han
378d0 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  dle. The impleme
378e0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
378f0 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a  methods defined.
37900 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ** by this struc
37910 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71  ture are not req
37920 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  uired to handle 
37930 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72  this case, the r
37940 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73  esults.** of pas
37950 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
37960 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
37970 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e   valid mutex han
37980 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65  dle are undefine
37990 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73  d.** (i.e. it is
379a0 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70   acceptable to p
379b0 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d  rovide an implem
379c0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65  entation that se
379d0 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74  gfaults if.** it
379e0 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c   is passed a NUL
379f0 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a  L pointer)..**.*
37a00 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74  * The xMutexInit
37a10 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 62  () method must b
37a20 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 5e  e threadsafe.  ^
37a30 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d 6c  It must be harml
37a40 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  ess to.** invoke
37a50 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75   xMutexInit() mu
37a60 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
37a70 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
37a80 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74 0a  ess and without.
37a90 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 63  ** intervening c
37aa0 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45 6e  alls to xMutexEn
37ab0 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64  d().  Second and
37ac0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37ad0 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49 6e  s to.** xMutexIn
37ae0 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f 2d  it() must be no-
37af0 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75 74  ops..**.** ^xMut
37b00 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e 6f  exInit() must no
37b10 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d  t use SQLite mem
37b20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  ory allocation (
37b30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37b40 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61 73  )].** and its as
37b50 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53 69 6d  sociates).  ^Sim
37b60 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41 6c  ilarly, xMutexAl
37b70 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20 75  loc() must not u
37b80 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79  se SQLite memory
37b90 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  .** allocation f
37ba0 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  or a static mute
37bb0 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78 4d 75  x.  ^However xMu
37bc0 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20 75  texAlloc() may u
37bd0 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d  se SQLite.** mem
37be0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
37bf0 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65 63  or a fast or rec
37c00 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a 2a  ursive mutex..**
37c10 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
37c20 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75 74   invoke the xMut
37c30 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20 77  exEnd() method w
37c40 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  hen [sqlite3_shu
37c50 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20 63  tdown()] is.** c
37c60 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79 20  alled, but only 
37c70 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61 6c  if the prior cal
37c80 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74 20  l to xMutexInit 
37c90 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f  returned SQLITE_
37ca0 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65 78  OK..** If xMutex
37cb0 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61 6e  Init fails in an
37cc0 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78 70  y way, it is exp
37cd0 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20 75  ected to clean u
37ce0 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a 2a  p after itself.*
37cf0 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75 72  * prior to retur
37d00 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ning..*/.typedef
37d10 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
37d20 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71  mutex_methods sq
37d30 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
37d40 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
37d50 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
37d60 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  s {.  int (*xMut
37d70 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20  exInit)(void);. 
37d80 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64   int (*xMutexEnd
37d90 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74  )(void);.  sqlit
37da0 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74  e3_mutex *(*xMut
37db0 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20  exAlloc)(int);. 
37dc0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72   void (*xMutexFr
37dd0 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ee)(sqlite3_mute
37de0 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
37df0 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69  MutexEnter)(sqli
37e00 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
37e10 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29  int (*xMutexTry)
37e20 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37e30 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
37e40 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33  exLeave)(sqlite3
37e50 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
37e60 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73   (*xMutexHeld)(s
37e70 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37e80 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e  .  int (*xMutexN
37e90 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  otheld)(sqlite3_
37ea0 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a  mutex *);.};../*
37eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
37ec0 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e  tex Verification
37ed0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
37ee0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
37ef0 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
37f00 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37f10 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
37f20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
37f30 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
37f40 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
37f50 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63  .  ^The SQLite c
37f60 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65  ore.** never use
37f70 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
37f80 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61   except inside a
37f90 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61  n assert() and a
37fa0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
37fb0 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f  re advised to fo
37fc0 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66  llow the lead of
37fd0 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54 68 65   the core.  ^The
37fe0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
37ff0 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d  y.** provides im
38000 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
38010 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
38020 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
38030 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  iled.** with the
38040 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c   SQLITE_DEBUG fl
38050 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c 20 6d  ag.  ^External m
38060 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
38070 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79  ions.** are only
38080 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
38090 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69  vide these routi
380a0 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45  nes if SQLITE_DE
380b0 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65  BUG is.** define
380c0 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20  d and if NDEBUG 
380d0 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a  is not defined..
380e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
380f0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74  tines should ret
38100 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
38110 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61  mutex in their a
38120 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65  rgument.** is he
38130 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20  ld or not held, 
38140 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79  respectively, by
38150 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
38160 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ead..**.** ^The 
38170 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
38180 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
38190 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69  o provided versi
381a0 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
381b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63  routines that ac
381c0 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20  tually work. If 
381d0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
381e0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  on does not prov
381f0 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76  ide working.** v
38200 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
38210 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68   routines, it sh
38220 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72  ould at least pr
38230 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74  ovide stubs that
38240 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72   always.** retur
38250 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f  n true so that o
38260 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20  ne does not get 
38270 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69  spurious asserti
38280 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
38290 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
382a0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ent to sqlite3_m
382b0 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61  utex_held() is a
382c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
382d0 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  en.** the routin
382e0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
382f0 31 2e 20 20 20 54 68 69 73 20 73 65 65 6d 73 20  1.   This seems 
38300 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76  counter-intuitiv
38310 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72  e since.** clear
38320 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e  ly the mutex can
38330 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 69  not be held if i
38340 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  t does not exist
38350 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68  .  But the.** th
38360 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74  e reason the mut
38370 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  ex does not exis
38380 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68 65  t is because the
38390 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a   build is not.**
383a0 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20   using mutexes. 
383b0 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77   And we do not w
383c0 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 29  ant the assert()
383d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
383e0 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
383f0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
38400 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f  to fail, so a no
38410 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73  n-zero return is
38420 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69  .** the appropri
38430 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e  ate thing to do.
38440 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d    ^The sqlite3_m
38450 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a  utex_notheld().*
38460 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  * interface shou
38470 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31  ld also return 1
38480 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55   when given a NU
38490 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 23  LL pointer..*/.#
384a0 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 69 6e  ifndef NDEBUG.in
384b0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
384c0 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
384d0 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
384e0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
384f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
38500 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
38510 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54  API3REF: Mutex T
38520 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ypes.**.** The [
38530 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
38540 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
38550 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
38560 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
38570 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
38580 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
38590 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
385a0 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74  et of static mut
385b0 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20  exes may change 
385c0 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20  from one SQLite 
385d0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a  release to the.*
385e0 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
385f0 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72  tions that overr
38600 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  ide the built-in
38610 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73   mutex logic mus
38620 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  t be.** prepared
38630 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20   to accommodate 
38640 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69  additional stati
38650 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64  c mutexes..*/.#d
38660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
38670 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20  EX_FAST         
38680 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
38690 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
386a0 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64  SIVE        1.#d
386b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
386c0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
386d0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
386e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
386f0 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f  C_MEM       3  /
38700 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
38710 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
38720 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
38730 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f  C_MEM2      4  /
38740 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64  * NOT USED */.#d
38750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
38760 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20  EX_STATIC_OPEN  
38770 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
38780 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a  3BtreeOpen() */.
38790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
387a0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
387b0 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
387c0 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
387d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
387e0 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
387f0 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
38800 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65  page list */.#de
38810 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
38820 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20  X_STATIC_LRU2   
38830 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67     7  /* lru pag
38840 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  e list */../*.**
38850 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
38860 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f  eve the mutex fo
38870 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
38880 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
38890 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
388a0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
388b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
388c0 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ex] object that 
388d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61  .** serializes a
388e0 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61  ccess to the [da
388f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase co