/ Hex Artifact Content
Login

Artifact a5b50e1bc4d4d9a3cc95386747220a839d0c40f7:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8580: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8590: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
85a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
85b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
85c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
85d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
85e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
85f0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8600: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8610: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8620: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8630: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8640: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8650: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8660: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8670: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8680: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8690: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
86a0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
86b0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
86c0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
86d0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
86e0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
86f0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8700: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8710: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8720: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8730: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8740: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8760: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8770: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8780: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8790: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
87a0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
87b0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
87c0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
87d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
87e0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
87f0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8800: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8810: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8820: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8830: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8840: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8850: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8860: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8870: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8880: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8890: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
88a0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
88b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
88c0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
88d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
88e0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
88f0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
8900: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
8910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8920: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
8930: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
8940: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
8950: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
8960: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
8970: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
8980: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
89a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
89b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
89c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
89d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
89e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
89f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
8a00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8a10: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8a20: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8a30: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
8a40: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
8a50: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
8a60: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8a70: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a80: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
8a90: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
8aa0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
8ab0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
8ac0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
8ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8ae0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8b00: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8b10: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8b20: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
8b30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8b40: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
8b50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8b60: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8b70: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8b80: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
8b90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ba0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8bb0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8bc0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
8bd0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
8be0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8bf0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8c00: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8c10: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8c20: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8c30: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8c40: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
8c50: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
8c60: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
8c70: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
8c80: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
8c90: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
8ca0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8cb0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8cc0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8cd0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8ce0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8cf0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8d00: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8d10: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8d20: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8d40: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
8d50: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
8d60: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
8d90: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
8da0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8db0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8dc0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8dd0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8de0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8df0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8e00: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8e10: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8e20: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8e30: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8e40: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8e60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8e80: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
8e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8ea0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8eb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8ec0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8ed0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8ee0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8ef0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
8f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8f10: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
8f20: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
8f30: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
8f40: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
8f50: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
8f60: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
8f70: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
8f80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8f90: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8fa0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
8fb0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
8fc0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
8fd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
8fe0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
8ff0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9000: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9010: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9020: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9030: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9040: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9050: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9060: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9070: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9080: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9090: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
90a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
90b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
90c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
90d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
90e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
90f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9100: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9110: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9120: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9130: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9140: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9150: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9160: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9170: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9180: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9190: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
91a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
91b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
91c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
91d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
91e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
91f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9200: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9210: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9220: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9230: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9240: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9250: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9260: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9280: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9290: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
92a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
92b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
92c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
92d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
92e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
92f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9300: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9310: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9320: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9330: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9340: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9350: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9360: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9370: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9380: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9390: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
93a0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
93b0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
93c0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
93d0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
93e0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
93f0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9400: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9410: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9420: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9430: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9440: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9450: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9460: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9470: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9480: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9490: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
94a0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
94b0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
94c0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
94d0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
94e0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
94f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9500: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9510: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9520: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9530: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9540: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9550: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9560: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9570: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9580: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9590: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
95a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
95b0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
95c0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
95d0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
95e0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
95f0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9600: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9610: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9620: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9630: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9640: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9650: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9660: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9680: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9690: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
96a0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
96b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
96c0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
96d0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
96e0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
96f0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9700: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9710: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9720: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9730: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9740: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9750: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9760: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9770: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9780: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9790: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
97a0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
97b0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
97c0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
97d0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
97e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
97f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9800: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9810: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9820: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9830: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9840: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9850: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9860: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9870: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9880: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9890: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
98a0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
98b0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
98c0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
98d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
98e0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
98f0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
9900: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
9910: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
9920: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
9930: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
9940: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
9950: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
9960: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
9970: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
9980: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
9990: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
99a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
99b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
99c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
99d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
99e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
99f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
9a00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
9a10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
9a20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
9a30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
9a40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9a50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
9a60: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
9a70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9a80: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9aa0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9ab0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9ac0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9ad0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
9ae0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
9af0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
9b00: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
9b10: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
9b20: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9b30: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9b40: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9b50: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9b60: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9b70: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9b80: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9b90: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9bb0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9bc0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
9bd0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
9be0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
9bf0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
9c00: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
9c10: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
9c20: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9c30: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9c40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9c50: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9c60: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9c70: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9c80: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9c90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9ca0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9cb0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9cc0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
9cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
9ce0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9cf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9d00: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
9d10: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
9d20: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9d30: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9d40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9d50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9d60: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9d70: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9d80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9d90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9da0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9db0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9dc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9dd0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
9de0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
9df0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
9e00: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
9e10: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
9e20: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9e30: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9e40: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9e50: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9e60: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9e70: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9e80: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9e90: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9ea0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9eb0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9ec0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9ed0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9ee0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
9ef0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
9f00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9f10: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
9f20: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9f30: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9f40: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9f50: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9f60: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9f70: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9f80: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9f90: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9fa0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9fb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9fc0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
9fd0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
9fe0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9ff0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a000: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a010: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a020: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a030: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a040: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a050: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a060: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a070: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a080: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a090: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a0a0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a0b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a0c0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a0d0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a0e0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a0f0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a100: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a110: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a120: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a130: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a140: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a150: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a160: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a170: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a180: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a190: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a1a0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a1b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a1c0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a1d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a1e0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a1f0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a200: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a210: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a220: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a230: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a240: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a250: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a260: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a270: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
a280: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
a290: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
a2a0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
a2b0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
a2c0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
a2d0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
a2e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a2f0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
a300: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
a310: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
a320: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
a330: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
a340: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
a350: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
a360: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
a370: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
a380: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
a390: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
a3a0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a3b0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
a3c0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
a3d0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
a3e0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
a3f0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
a400: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
a410: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
a420: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
a430: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
a440: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a450: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
a460: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
a470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a480: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
a490: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
a4a0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
a4b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a4c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
a4d0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
a4e0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
a4f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
a500: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
a510: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
a520: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
a530: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
a540: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
a550: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
a560: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
a570: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
a580: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a590: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
a5a0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
a5b0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
a5c0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
a5d0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
a5e0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
a5f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
a610: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
a620: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
a630: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
a640: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a650: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
a660: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
a670: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a680: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a690: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a6b0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
a6c0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
a6d0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
a6e0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
a6f0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
a700: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
a710: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
a720: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
a730: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
a740: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
a750: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
a760: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
a770: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
a780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
a790: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
a7a0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
a7b0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
a7c0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
a7d0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
a7f0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
a800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
a810: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
a820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
a830: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
a840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a850: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
a860: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
a870: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
a880: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
a890: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
a8a0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
a8b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
a8c0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
a8d0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
a8e0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
a8f0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
a900: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
a910: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
a920: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
a930: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
a940: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
a950: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
a960: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
a970: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
a980: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
a990: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
a9a0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
a9b0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
a9c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a9d0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a9e0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
a9f0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
aa00: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
aa10: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
aa20: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
aa30: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
aa40: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
aa50: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
aa60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
aa70: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
aa80: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
aa90: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
aaa0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
aab0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
aac0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
aad0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
aae0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
aaf0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ab00: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ab10: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ab20: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ab30: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ab40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ab50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
ab60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ab70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
ab80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ab90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aba0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
abb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
abc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
abd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
abe0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
abf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ac00: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ac10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ac20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ac30: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ac40: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
ac50: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
ac60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ac70: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
ac80: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
ac90: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
aca0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
acb0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
acc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
acd0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ace0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
acf0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ad00: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ad10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ad20: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ad30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ad40: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
ad50: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
ad60: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ad70: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
ad80: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
ad90: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
ada0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
adb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
adc0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
add0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ade0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
adf0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ae00: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ae10: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ae20: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ae30: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ae40: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ae50: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ae60: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ae70: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ae80: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ae90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
aea0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
aeb0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
aec0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
aed0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
aee0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
aef0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
af00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
af10: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
af20: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
af30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
af40: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
af50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
af60: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
af70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
af80: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
af90: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
afa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afc0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
afd0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
afe0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
aff0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b000: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b010: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b020: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b030: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b040: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b050: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b060: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b070: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b080: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b090: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b0a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b0b0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b0c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b0d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b0e0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b0f0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b100: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b110: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b120: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b130: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b140: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b150: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b160: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b170: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b190: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b1b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b1c0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b1d0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b1e0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b1f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b200: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b210: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b220: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b230: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b240: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b250: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b260: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b270: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
b280: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
b290: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
b2a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b2b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
b2c0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
b2d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b2e0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
b2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b300: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
b310: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
b320: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
b330: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
b340: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
b350: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
b360: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
b370: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
b380: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
b390: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
b3a0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
b3b0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
b3c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3d0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
b3e0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
b3f0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
b400: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
b410: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
b420: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
b430: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b440: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
b450: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
b460: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
b470: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
b480: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
b490: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
b4a0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
b4b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
b4c0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
b4d0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
b4e0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
b4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
b500: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
b510: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
b520: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
b530: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
b540: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
b550: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
b560: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
b570: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
b580: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
b590: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
b5a0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
b5b0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
b5c0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
b5d0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
b5e0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
b5f0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
b600: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
b610: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
b620: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
b630: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
b640: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
b650: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
b660: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b670: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
b680: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
b690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
b6a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
b6b0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
b6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b6d0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
b6e0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
b6f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
b700: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b710: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b720: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
b730: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
b740: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
b750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b760: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
b770: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
b780: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
b790: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
b7a0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
b7b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
b7c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
b7d0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
b7e0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
b7f0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
b800: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
b810: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
b820: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
b830: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
b840: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
b850: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
b860: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
b870: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
b880: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
b890: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
b8a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b8b0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
b8c0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
b8d0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
b8e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
b8f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
b900: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
b910: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
b920: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b930: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
b940: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
b950: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
b960: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
b970: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
b980: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
b990: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
b9a0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
b9b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
b9c0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
b9d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
b9e0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
b9f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
ba00: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ba10: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
ba20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ba30: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
ba40: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
ba50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ba60: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ba70: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ba80: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
ba90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
baa0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
bab0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
bac0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
bad0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
bae0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
baf0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
bb00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
bb10: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
bb20: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
bb30: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
bb40: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
bb50: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
bb60: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
bb70: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
bb80: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
bb90: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
bba0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
bbb0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bbc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bbd0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
bbe0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbf0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
bc00: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
bc10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
bc20: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
bc30: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
bc40: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
bc50: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
bc60: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
bc70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bc80: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
bc90: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
bca0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
bcb0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
bcc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
bcd0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
bce0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
bcf0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bd00: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
bd10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
bd20: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
bd30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bd40: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
bd50: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
bd60: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
bd70: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
bd80: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
bd90: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
bda0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
bdb0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
bdc0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
bdd0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
bde0: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
bdf0: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
be00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
be10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
be20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
be30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
be40: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
be50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
be60: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
be70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
be80: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
be90: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
bea0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
beb0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
bec0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
bed0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
bee0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
bef0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bf00: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
bf10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bf20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
bf30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
bf40: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
bf50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bf60: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
bf70: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
bf80: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
bf90: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
bfa0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
bfb0: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
bfc0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
bfd0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
bfe0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
bff0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
c000: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
c010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
c020: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
c030: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c040: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
c050: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
c060: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
c070: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c090: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
c0a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
c0b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c0c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
c0d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
c0e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c0f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
c100: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
c110: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
c120: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
c130: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
c140: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
c150: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
c160: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
c170: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
c180: 72 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c  rface should onl
c190: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c1a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c1b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c1c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c1d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c1e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c1f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c200: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c210: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c220: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c230: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c240: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c250: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c260: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c270: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c280: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c290: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c2a0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c2c0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c2d0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c2e0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c2f0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c300: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c310: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c320: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c330: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c340: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c350: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c360: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c370: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c380: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
c390: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
c3a0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
c3b0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
c3c0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
c3d0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
c3e0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
c3f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
c400: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
c410: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
c420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c430: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
c440: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
c450: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c460: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c470: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c480: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
c490: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
c4a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4b0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
c4c0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
c4d0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
c4e0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
c4f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c500: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
c510: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
c520: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
c530: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
c540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c550: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
c560: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c570: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
c580: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c590: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
c5a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
c5b0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
c5c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
c5d0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
c5e0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
c5f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
c600: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
c610: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
c620: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
c630: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c640: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
c650: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
c660: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c670: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
c680: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
c690: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
c6a0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
c6b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
c6c0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
c6d0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
c6e0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
c6f0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
c700: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
c710: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
c720: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
c730: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
c740: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
c750: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
c760: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
c770: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
c780: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
c790: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
c7a0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
c7b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
c7c0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
c7d0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
c7e0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c7f0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
c800: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
c810: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
c820: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
c830: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
c840: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
c850: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
c860: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
c870: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
c880: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
c890: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
c8a0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
c8b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
c8c0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
c8d0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
c8e0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
c8f0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
c900: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
c910: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
c920: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
c930: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
c940: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
c950: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
c960: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
c970: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
c980: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
c990: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c9a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
c9b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
c9c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
c9d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
c9e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
c9f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
ca00: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
ca10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ca20: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
ca30: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
ca40: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
ca50: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
ca60: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
ca70: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
ca80: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
ca90: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
caa0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
cab0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
cac0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
cad0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
cae0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
caf0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
cb00: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
cb10: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
cb20: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
cb30: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
cb40: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
cb50: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
cb60: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
cb70: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
cb80: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
cb90: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
cba0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
cbb0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
cbc0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
cbd0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
cbe0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
cbf0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
cc00: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
cc10: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
cc20: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
cc30: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
cc40: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cc50: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
cc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
cc70: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
cc80: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
cc90: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
cca0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
ccb0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
ccc0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
ccd0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
cce0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
ccf0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
cd00: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
cd10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
cd20: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
cd30: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
cd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
cd50: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
cd60: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
cd70: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
cd80: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
cd90: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
cda0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
cdb0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
cdc0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
cdd0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
cde0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
cdf0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
ce00: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ce10: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
ce20: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ce30: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
ce40: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
ce50: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
ce60: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
ce70: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
ce80: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
ce90: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cea0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
ceb0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cec0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
ced0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cee0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cef0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cf00: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cf10: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cf20: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cf30: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
cf40: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
cf50: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
cf60: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
cf70: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
cf80: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
cf90: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
cfa0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
cfb0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
cfc0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
cfd0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
cfe0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
cff0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
d000: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d010: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
d020: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
d030: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
d040: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
d050: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
d060: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
d070: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
d080: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
d090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d0a0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
d0b0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
d0c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
d0d0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
d0e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d0f0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
d100: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
d110: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
d120: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
d130: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
d140: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
d150: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
d160: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d170: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
d180: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
d190: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
d1a0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
d1b0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
d1c0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
d1d0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
d1e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
d1f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
d200: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
d210: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
d220: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
d230: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
d240: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
d250: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d260: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d270: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
d280: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
d290: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d2a0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
d2b0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
d2c0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
d2d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d2e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
d2f0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
d300: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
d310: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
d320: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
d330: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
d340: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
d350: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
d360: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
d370: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
d380: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
d390: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
d3a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
d3b0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
d3c0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
d3d0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
d3e0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
d3f0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
d400: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
d410: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
d420: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
d430: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d440: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
d450: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
d460: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
d470: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d480: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d490: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
d4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
d4b0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
d4c0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
d4d0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
d4e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d4f0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
d500: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
d510: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
d520: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
d530: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
d540: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
d550: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
d560: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
d570: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
d580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
d590: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d5a0: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
d5b0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
d5c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d5d0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
d5e0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
d5f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d600: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
d610: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
d620: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
d630: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
d640: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
d650: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d660: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
d670: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
d680: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
d690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d6a0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d6b0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d6c0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d6d0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d6e0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d6f0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d700: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d710: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
d720: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
d730: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d740: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d750: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d760: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d770: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
d780: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d790: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
d7a0: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
d7b0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
d7c0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
d7d0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d7e0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d7f0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d800: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d810: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d820: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d830: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d840: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d850: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d860: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d870: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d880: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d890: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d8a0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d8b0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
d8c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
d8d0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
d8e0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
d8f0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
d900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d910: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
d920: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d930: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d940: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
d950: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
d960: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d970: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d980: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d990: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d9a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d9b0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d9c0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d9d0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
d9e0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
d9f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
da00: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
da10: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
da20: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
da30: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
da40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
da50: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
da60: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
da70: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
da80: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
da90: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
daa0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
dab0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
dac0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dad0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
dae0: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
daf0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
db00: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
db10: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
db20: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
db30: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
db40: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
db50: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
db60: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
db70: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
db80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
db90: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
dba0: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
dbb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dbc0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dbd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dbe0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dbf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc10: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc20: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
dc30: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
dc40: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
dc50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
dc60: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
dc70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
dc80: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
dc90: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
dca0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
dcb0: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
dcc0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
dcd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dce0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
dcf0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
dd00: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
dd10: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
dd20: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
dd30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
dd40: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dd50: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
dd60: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
dd70: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
dd80: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
dd90: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
dda0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
ddb0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
ddc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
ddd0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
dde0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
ddf0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
de00: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
de10: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
de20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de30: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
de40: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
de50: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
de60: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
de70: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
de80: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
de90: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
dea0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
deb0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
dec0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
ded0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
dee0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
def0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
df00: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
df10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
df20: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
df30: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
df40: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
df50: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
df60: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
df70: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
df80: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
df90: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
dfa0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
dfb0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
dfc0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
dfd0: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
dfe0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
dff0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
e000: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
e010: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e020: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e030: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
e040: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e050: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
e060: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e070: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e080: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
e090: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e0a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e0b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e0c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e0d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e0e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e0f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e100: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
e110: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
e120: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
e130: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
e140: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e150: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e160: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
e170: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
e180: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e190: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
e1a0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
e1b0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
e1c0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
e1d0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
e1e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
e1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e200: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
e210: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e220: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
e230: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e240: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
e250: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
e260: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e270: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e280: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e290: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e2a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e2b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e2d0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
e2e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e2f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e300: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e310: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e320: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
e330: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
e340: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
e350: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
e360: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
e370: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e380: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
e390: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
e3a0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
e3b0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
e3c0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
e3d0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
e3e0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
e3f0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
e400: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e410: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
e420: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e430: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
e440: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
e450: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
e460: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
e470: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
e480: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
e490: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
e4a0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
e4b0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
e4c0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
e4d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e4e0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
e4f0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
e500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
e510: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
e520: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
e530: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
e540: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
e550: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
e560: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e570: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
e580: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
e590: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
e5a0: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
e5b0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
e5c0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
e5d0: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
e5e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e5f0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
e600: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
e610: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
e620: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
e630: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
e640: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
e650: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
e660: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
e670: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
e680: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
e690: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
e6a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e6b0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
e6c0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
e6d0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
e6e0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
e6f0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
e700: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
e710: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
e720: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
e730: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e740: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
e750: 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
e760: 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
e770: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
e780: 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f  scrach allocatio
e790: 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
e7a0: 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
e7b0: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
e7c0: 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
e7d0: 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
e7e0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
e7f0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
e800: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
e810: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
e820: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
e830: 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
e840: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
e850: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e860: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
e870: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
e880: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e890: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
e8a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e8b0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
e8c0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
e8d0: 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
e8e0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
e8f0: 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
e900: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
e910: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
e920: 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
e930: 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
e940: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
e950: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
e960: 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
e970: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
e980: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
e990: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
e9a0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
e9b0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
e9c0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e9d0: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
e9e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e9f0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
ea00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
ea10: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
ea20: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
ea30: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
ea40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ea50: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
ea60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ea70: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
ea80: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
ea90: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
eaa0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
eab0: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
eac0: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
ead0: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
eae0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
eaf0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
eb00: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
eb10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
eb20: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
eb30: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
eb40: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
eb50: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
eb60: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
eb70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
eb80: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
eb90: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
eba0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ebb0: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
ebc0: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
ebd0: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
ebe0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
ebf0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
ec00: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
ec10: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
ec20: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
ec30: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
ec40: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
ec50: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
ec60: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
ec70: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
ec80: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
ec90: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
eca0: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
ecb0: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
ecc0: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
ecd0: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
ece0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
ecf0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
ed00: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
ed10: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
ed20: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
ed30: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
ed40: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
ed50: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
ed60: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
ed70: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
ed80: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
ed90: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
eda0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
edb0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
edc0: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
edd0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
ede0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
edf0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
ee00: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
ee10: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
ee20: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
ee30: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
ee40: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
ee50: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
ee60: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
ee70: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
ee80: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
ee90: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
eea0: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
eeb0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
eec0: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
eed0: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
eee0: 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
eef0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ef00: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
ef10: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
ef20: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
ef30: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
ef40: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
ef50: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
ef60: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
ef70: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ef80: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
ef90: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
efa0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
efb0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
efc0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
efd0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
efe0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
eff0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f000: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
f010: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
f020: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
f030: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
f040: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
f050: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
f060: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
f070: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
f080: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
f090: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
f0a0: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
f0b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
f0c0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
f0d0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
f0e0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
f0f0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
f100: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
f110: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
f120: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
f130: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
f140: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
f150: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
f160: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
f170: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
f180: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
f190: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
f1a0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
f1b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f1c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
f1d0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
f1e0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
f1f0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
f200: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
f210: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
f220: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
f230: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
f240: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
f250: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
f260: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
f270: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
f280: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
f290: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
f2a0: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
f2b0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
f2c0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
f2d0: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
f2e0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
f2f0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
f300: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
f310: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
f320: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
f330: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f340: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
f350: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f360: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f370: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f380: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f390: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
f3a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
f3b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f3c0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f3d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
f3e0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
f3f0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
f400: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
f410: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
f420: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
f430: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
f440: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
f450: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
f460: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
f470: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
f480: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f490: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
f4a0: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
f4b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f4c0: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
f4d0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
f4e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
f4f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
f500: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
f510: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
f520: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f530: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
f540: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
f550: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
f560: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
f570: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
f580: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
f590: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
f5a0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
f5b0: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
f5c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
f5d0: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
f5e0: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
f5f0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f600: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
f610: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
f620: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f630: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f640: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f650: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f660: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
f670: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
f680: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
f690: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
f6a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f6b0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
f6c0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
f6d0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
f6e0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
f6f0: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
f700: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
f710: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
f720: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
f730: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
f740: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
f750: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
f760: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
f770: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
f780: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
f790: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
f7a0: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
f7b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f7c0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
f7d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
f7e0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
f7f0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
f800: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
f810: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
f820: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
f830: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
f840: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
f850: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
f860: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f870: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
f880: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
f890: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
f8a0: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
f8b0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
f8c0: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
f8d0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f8e0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
f8f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f900: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f910: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
f920: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
f930: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
f940: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
f950: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
f960: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f970: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
f980: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f990: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
f9a0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
f9b0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
f9c0: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
f9d0: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
f9e0: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
f9f0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
fa00: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
fa10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fa20: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
fa30: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
fa40: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
fa50: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
fa60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
fa70: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
fa80: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
fa90: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
faa0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
fab0: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
fac0: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
fad0: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
fae0: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
faf0: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
fb00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fb10: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
fb20: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fb30: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
fb40: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
fb50: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
fb60: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
fb70: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
fb80: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
fb90: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
fba0: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
fbb0: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
fbc0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
fbd0: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
fbe0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
fbf0: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
fc00: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
fc10: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
fc20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
fc30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fc40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
fc50: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
fc60: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
fc70: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
fc80: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
fc90: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
fca0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
fcb0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
fcc0: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
fcd0: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
fce0: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
fcf0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fd00: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
fd10: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
fd20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fd30: 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
fd40: 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
fd50: 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
fd60: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
fd70: 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
fd80: 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
fd90: 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
fda0: 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
fdb0: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
fdc0: 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
fdd0: 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
fde0: 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
fdf0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
fe00: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
fe10: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
fe20: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
fe30: 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
fe40: 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
fe50: 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
fe60: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
fe70: 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
fe80: 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
fe90: 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
fea0: 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
feb0: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
fec0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
fed0: 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
fee0: 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
fef0: 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
ff00: 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
ff10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
ff20: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
ff30: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
ff40: 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
ff50: 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
ff60: 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
ff70: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
ff80: 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
ff90: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
ffa0: 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
ffb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
ffc0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
ffd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
ffe0: 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
fff0: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
10000 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
10010 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
10020 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
10030 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
10040 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
10050 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
10060 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
10070 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
10080 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
10090 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
100a0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
100b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
100c0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
100d0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
100e0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
100f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
10100 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
10110 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
10120 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
10130 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
10140 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
10150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
10160 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
10170 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
10180 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
10190 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
101a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
101b0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
101c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
101d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
101e0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
101f0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
10200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10210 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
10220 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
10230 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10240 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
10250 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
10260 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10270 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10280 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
10290 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
102a0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
102b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
102c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
102d0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
102e0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
102f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10300 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
10310 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
10320 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
10330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10340 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
10350 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
10360 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
10370 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
10380 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10390 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
103a0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
103b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
103c0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
103d0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
103e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
103f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10400 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10410 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
10420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10430 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
10440 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
10450 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
10460 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
10470 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
10480 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10490 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
104a0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
104b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
104c0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
104d0 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
104e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
104f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10500 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
10510 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
10520 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10530 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10540 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10550 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
10560 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
10570 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
10590 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
105a0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
105b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
105c0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
105d0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
105e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105f0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
10600 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
10610 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10620 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
10630 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
10640 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
10650 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10660 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10670 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10680 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10690 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
106a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106b0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
106c0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
106d0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
106e0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
106f0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
10700 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10710 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
10720 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
10730 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
10740 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
10750 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10760 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10770 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10780 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10790 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
107a0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
107b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
107c0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
107d0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
107e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
107f0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
10800 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10810 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
10820 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
10830 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
10840 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
10850 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
10860 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
10870 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
10880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10890 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
108a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
108b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
108c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
108d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
108e0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
108f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10900 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
10910 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
10920 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10930 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
10940 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10950 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
10960 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
10970 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
10980 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
10990 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
109a0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
109b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
109c0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
109d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
109e0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
109f0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
10a00 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
10a10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
10a20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
10a30 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
10a40 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
10a50 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
10a60 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10a70 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
10a80 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
10a90 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
10aa0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
10ab0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
10ac0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
10ad0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
10ae0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
10af0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
10b00 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10b10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10b20 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
10b30 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
10b40 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
10b50 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
10b60 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
10b70 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
10b80 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
10b90 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
10ba0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
10bb0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
10bc0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
10bd0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
10be0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
10bf0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
10c00 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
10c10 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
10c20 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
10c30 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
10c40 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
10c50 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
10c60 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
10c70 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
10c80 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
10c90 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
10ca0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
10cb0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
10cc0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
10cd0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
10ce0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
10cf0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
10d00 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10d10 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
10d20 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
10d30 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
10d40 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
10d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
10d60 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10d70 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
10d80 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
10d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10da0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
10db0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
10dc0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
10dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
10de0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
10df0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
10e00 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
10e10 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
10e20 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
10e30 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
10e40 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
10e50 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
10e60 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
10e70 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
10e80 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
10e90 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
10ea0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
10eb0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
10ec0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
10ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10ee0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
10ef0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
10f00 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
10f10 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
10f20 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
10f30 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
10f40 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
10f50 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
10f60 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
10f70 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
10f80 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
10f90 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
10fa0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
10fb0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
10fc0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
10fd0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
10fe0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
10ff0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
11000 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
11010 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
11020 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
11030 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
11040 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
11050 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
11060 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
11070 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
11080 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11090 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
110a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
110b0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
110c0 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
110d0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
110e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
110f0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
11100 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
11110 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
11120 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
11130 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
11140 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
11150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
11160 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
11170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
11180 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
11190 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
111a0 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
111b0 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
111c0 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
111d0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
111e0 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
111f0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
11200 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
11210 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
11220 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
11230 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11240 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
11250 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
11260 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
11270 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
11280 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
11290 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
112a0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
112b0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
112c0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
112d0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
112e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
112f0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
11300 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
11310 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
11320 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
11330 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
11340 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
11350 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
11360 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
11370 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
11380 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
11390 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
113a0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
113b0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
113c0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
113d0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
113e0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
113f0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
11400 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
11410 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
11420 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
11430 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
11440 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
11450 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
11460 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
11470 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
11480 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
11490 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
114a0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
114b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
114c0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
114d0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
114e0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
114f0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
11500 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
11510 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
11520 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
11530 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
11540 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
11550 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
11560 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
11570 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
11580 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
11590 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
115a0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
115b0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
115c0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
115d0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
115e0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
115f0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
11600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
11610 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
11620 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
11630 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
11640 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
11650 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
11660 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
11670 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
11680 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11690 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
116a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
116b0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
116c0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
116d0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
116e0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
116f0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
11700 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
11710 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
11720 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
11730 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
11740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11750 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
11760 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
11770 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
11780 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
117a0 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
117b0 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
117c0 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
117d0 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
117e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
117f0 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
11800 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
11810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11820 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
11830 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
11840 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
11850 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
11860 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
11870 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
11880 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
11890 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
118a0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
118b0 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
118c0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
118d0 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
118e0 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
118f0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
11900 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
11910 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
11920 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
11930 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
11940 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
11950 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
11960 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
11970 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
11980 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
11990 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
119a0 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
119b0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
119c0 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
119d0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
119e0 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
119f0 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
11a00 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
11a10 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
11a20 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
11a30 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
11a40 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
11a50 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
11a60 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
11a70 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
11a80 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
11a90 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
11aa0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
11ab0 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
11ac0 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
11ad0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
11ae0 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
11af0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
11b00 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
11b10 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
11b20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
11b30 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
11b40 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
11b50 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
11b60 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
11b70 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
11b80 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
11b90 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
11ba0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
11bb0 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
11bc0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
11bd0 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
11be0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
11bf0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
11c00 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
11c10 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
11c20 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
11c30 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
11c40 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
11c50 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
11c60 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
11c70 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
11c80 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
11c90 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
11ca0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
11cb0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
11cc0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
11cd0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
11ce0 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
11cf0 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
11d00 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
11d10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
11d20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
11d30 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
11d40 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
11d50 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
11d60 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
11d70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
11d80 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
11d90 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
11da0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11db0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11dc0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
11dd0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
11de0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11df0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
11e00 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
11e10 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
11e20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
11e30 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
11e40 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
11e50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
11e60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11e70 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
11e80 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
11e90 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
11ea0 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
11eb0 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
11ec0 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
11ed0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
11ee0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
11ef0 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
11f00 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
11f10 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
11f20 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
11f30 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
11f40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
11f50 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
11f60 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
11f70 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
11f80 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
11f90 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
11fa0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
11fb0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
11fc0 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
11fd0 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
11fe0 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
11ff0 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
12000 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
12010 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12020 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
12030 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
12040 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
12050 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
12060 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
12070 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
12080 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
12090 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
120a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
120b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
120c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
120d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
120e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
120f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
12100 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
12110 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
12120 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12130 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
12140 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12150 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
12160 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
12170 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
12180 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
12190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
121a0 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
121b0 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
121c0 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
121d0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
121e0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
121f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12200 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
12210 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
12220 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
12230 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
12240 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
12250 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
12260 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
12270 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
12280 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
12290 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
122a0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
122b0 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
122c0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
122d0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
122e0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
122f0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
12300 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
12310 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
12320 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
12330 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
12340 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
12350 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
12360 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
12370 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
12380 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
12390 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
123a0 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
123b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
123c0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
123d0 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
123e0 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
123f0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
12400 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
12410 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
12420 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
12430 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
12440 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
12450 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
12460 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
12470 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
12480 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
12490 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
124a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
124b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
124c0 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
124d0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
124e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
124f0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12500 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12510 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12520 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
12530 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
12540 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
12550 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
12560 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
12570 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
12580 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
12590 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
125a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
125b0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
125c0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
125d0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
125e0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
125f0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
12600 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
12610 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
12620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12630 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
12640 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
12650 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12660 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
12670 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
12680 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
12690 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
126a0 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
126b0 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
126c0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
126d0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
126e0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
126f0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
12700 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
12710 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
12720 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
12730 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
12740 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
12750 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
12760 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
12770 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
12780 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
12790 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
127a0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
127b0 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
127c0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
127d0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
127e0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
127f0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
12800 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12810 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
12820 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12830 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
12840 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
12850 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
12860 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12870 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
12880 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
12890 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
128a0 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
128b0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
128c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
128d0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
128e0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
128f0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
12900 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
12910 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
12920 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
12930 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
12940 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
12950 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
12960 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
12970 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12980 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
12990 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
129a0 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
129b0 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
129c0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
129d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
129e0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
129f0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
12a00 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
12a10 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
12a20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
12a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
12a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
12a50 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
12a60 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
12a70 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
12a80 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
12a90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
12aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12ab0 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
12ac0 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
12ad0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12ae0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12af0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
12b00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
12b10 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
12b20 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
12b30 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
12b40 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
12b50 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
12b60 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
12b70 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
12b80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12b90 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
12ba0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
12bb0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
12bc0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
12bd0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12be0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
12bf0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
12c00 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
12c10 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12c20 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
12c30 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
12c40 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
12c50 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
12c60 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
12c70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
12c80 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
12c90 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12ca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12cb0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12cc0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
12cd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12ce0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
12cf0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
12d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
12d10 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
12d20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12d30 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
12d40 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
12d50 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
12d60 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
12d70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
12d80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12d90 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
12da0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
12db0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
12dc0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
12dd0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
12de0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
12df0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
12e00 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
12e10 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
12e20 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
12e30 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
12e40 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12e50 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
12e60 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
12e70 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
12e80 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
12e90 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
12ea0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
12eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
12ec0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
12ed0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
12ee0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
12ef0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12f00 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
12f10 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
12f20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
12f30 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
12f40 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
12f50 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
12f60 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
12f70 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
12f80 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
12f90 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
12fa0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
12fb0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
12fc0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
12fd0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
12fe0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
12ff0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
13000 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
13010 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
13020 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
13030 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
13040 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
13050 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
13060 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
13070 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
13080 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
13090 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
130a0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
130b0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
130c0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
130d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
130e0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
130f0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
13100 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
13110 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13120 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
13130 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
13140 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
13150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
13160 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
13170 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
13180 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
13190 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
131a0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
131b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
131c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
131d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
131e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
131f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
13200 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
13210 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13220 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
13230 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
13240 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
13250 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
13260 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13270 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
13280 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
13290 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
132a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
132b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
132c0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
132d0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
132e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
132f0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
13300 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
13310 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
13320 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
13330 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
13340 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
13350 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
13360 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
13370 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
13380 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
13390 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
133a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
133b0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
133c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
133d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
133e0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
133f0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
13400 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13410 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
13420 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
13430 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
13440 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
13450 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
13460 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
13470 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13480 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
13490 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
134a0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
134b0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
134c0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
134d0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
134e0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
134f0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
13500 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
13510 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
13520 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
13530 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
13540 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
13550 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13560 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
13570 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
13580 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
13590 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
135a0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
135b0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
135c0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
135d0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
135e0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
135f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
13600 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13610 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
13620 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
13630 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
13640 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
13650 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
13660 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
13670 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
13680 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
13690 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
136a0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
136b0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
136c0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
136d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
136e0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
136f0 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
13700 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
13710 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
13720 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
13730 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
13740 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
13750 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
13760 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
13770 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
13780 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
13790 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
137a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
137b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
137c0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
137d0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
137e0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
137f0 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
13800 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
13810 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
13820 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
13830 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
13840 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
13850 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
13860 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
13870 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
13880 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
13890 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
138a0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
138b0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
138c0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
138d0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
138e0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
138f0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
13900 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13910 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
13920 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13930 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13940 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13950 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13960 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13970 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
13980 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13990 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
139a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
139b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
139c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
139d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
139e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
139f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
13a00 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
13a10 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
13a20 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13a30 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13a40 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13a50 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13a60 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13a70 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13a80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13a90 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
13aa0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
13ab0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
13ac0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
13ad0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
13ae0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
13af0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
13b00 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
13b10 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
13b20 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13b30 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13b40 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13b50 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13b60 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13b70 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13b80 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13b90 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
13ba0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
13bb0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
13bc0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
13bd0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
13be0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
13bf0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
13c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
13c10 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
13c20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
13c30 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13c40 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
13c50 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
13c60 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
13c70 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
13c80 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
13c90 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
13ca0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
13cb0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
13cc0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
13cd0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
13ce0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
13cf0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
13d00 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
13d10 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
13d20 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
13d30 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
13d40 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
13d50 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
13d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
13d70 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
13d80 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
13d90 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
13da0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
13db0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
13dc0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
13dd0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
13de0 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
13df0 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
13e00 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
13e10 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
13e20 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
13e30 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
13e40 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
13e50 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
13e60 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
13e70 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
13e80 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
13e90 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
13ea0 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
13eb0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
13ec0 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
13ed0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
13ee0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
13ef0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13f00 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
13f10 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
13f20 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
13f30 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
13f40 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
13f50 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
13f60 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
13f70 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
13f80 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
13f90 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
13fa0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
13fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13fc0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
13fd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
13fe0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
13ff0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
14000 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
14010 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
14020 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14030 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
14040 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
14050 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
14060 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
14070 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
14080 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
14090 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
140a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
140b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
140c0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
140d0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
140e0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
140f0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
14100 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
14110 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
14120 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
14130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14140 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
14150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14160 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
14170 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14180 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
14190 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
141a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
141b0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
141c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
141d0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
141e0 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
141f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
14200 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
14210 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
14220 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
14230 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
14240 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
14250 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
14260 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
14270 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
14280 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
14290 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
142a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
142b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
142c0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
142d0 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
142e0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
142f0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
14300 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
14310 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
14320 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
14330 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
14340 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
14350 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
14360 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14370 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
14380 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
14390 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
143a0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
143b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
143c0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
143d0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
143e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
143f0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
14400 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
14410 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
14420 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
14430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
14440 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
14450 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
14460 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
14470 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
14480 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
14490 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
144a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
144b0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
144c0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
144d0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
144e0 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
144f0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
14500 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
14510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14520 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
14530 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
14540 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
14550 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
14560 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
14570 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
14580 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14590 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
145a0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
145b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
145c0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
145d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
145e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
145f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
14600 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
14610 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
14620 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14630 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
14640 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
14650 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
14660 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
14670 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
14680 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
14690 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
146a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
146b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
146c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
146d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
146e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
146f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
14700 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
14710 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
14720 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
14730 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
14740 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14750 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
14760 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
14770 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
14780 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
14790 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
147a0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
147b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
147c0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
147d0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
147e0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
147f0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
14800 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
14810 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14820 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14830 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14840 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14850 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14860 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14870 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14880 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14890 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
148a0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
148b0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
148c0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
148d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
148e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
148f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
14900 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
14910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
14920 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
14930 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
14940 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
14950 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
14960 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
14970 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
14980 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
14990 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
149a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
149b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
149c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
149d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
149e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
149f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
14a00 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
14a10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14a20 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
14a30 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
14a40 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
14a50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14a60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14a70 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
14a80 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
14a90 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
14aa0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
14ab0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
14ac0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
14ad0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
14ae0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
14af0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
14b00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14b10 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
14b20 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
14b30 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
14b40 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
14b50 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
14b60 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
14b70 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
14b80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
14b90 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
14ba0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
14bb0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
14bc0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
14bd0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
14be0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14bf0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
14c00 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
14c10 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
14c20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
14c30 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
14c40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14c50 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
14c60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14c70 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
14c80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14c90 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
14ca0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
14cb0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
14cc0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
14cd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
14ce0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
14cf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14d00 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
14d10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14d20 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
14d30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14d40 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
14d50 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
14d60 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
14d70 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
14d80 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
14d90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14da0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
14db0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
14dc0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
14dd0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
14de0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
14df0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
14e00 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
14e10 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
14e20 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
14e30 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
14e40 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
14e50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14e60 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
14e70 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
14e80 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
14e90 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14ea0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14eb0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14ec0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14ed0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14ee0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14ef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14f00 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14f10 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14f20 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14f30 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14f40 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14f50 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14f60 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14f70 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14f80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14f90 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14fa0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14fb0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14fc0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14fd0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14fe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14ff0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
15000 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
15010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
15020 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
15030 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
15040 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
15050 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
15060 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
15070 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
15080 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
15090 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
150a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
150b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
150c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
150d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
150e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
150f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
15100 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
15110 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
15120 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
15130 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
15140 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
15150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
15160 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
15170 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15190 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
151a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
151b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
151c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
151d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
151e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
151f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15200 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15210 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15220 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
15230 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
15240 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
15250 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
15260 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
15270 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
15280 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15290 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
152a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
152b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
152c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
152d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
152e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
152f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15300 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15310 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15320 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
15330 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
15340 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
15350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
15360 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
15370 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
15380 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
15390 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
153a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
153b0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
153c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
153d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
153e0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
153f0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
15400 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
15410 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
15420 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15430 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
15440 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
15450 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
15460 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
15470 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
15480 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
15490 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
154a0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
154b0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
154c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
154d0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
154e0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
154f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
15500 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
15510 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73  ng..**.** ^(In s
15520 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15530 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
15540 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
15550 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
15560 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
15570 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
15580 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
15590 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
155a0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
155b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
155c0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
155d0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
155e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
155f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
15600 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
15610 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
15620 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
15630 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
15640 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
15650 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
15660 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
15670 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
15680 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
15690 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
156a0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
156b0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
156c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
156d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
156e0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
156f0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
15700 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
15710 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
15720 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
15730 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
15740 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
15750 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
15760 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
15770 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
15780 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
15790 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
157a0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
157b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
157c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
157d0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
157e0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
157f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
15800 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
15810 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
15820 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
15830 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15840 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
15850 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
15860 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
15870 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
15880 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
15890 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
158a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
158b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
158c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
158d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
158e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
158f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
15900 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
15910 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
15920 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
15930 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
15940 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
15950 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
15960 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
15970 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
15980 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
15990 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
159a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
159b0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
159c0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
159d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
159e0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
159f0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
15a00 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
15a10 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
15a20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
15a30 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
15a40 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
15a50 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
15a60 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
15a70 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
15a80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
15a90 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
15aa0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
15ab0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
15ac0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
15ad0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
15ae0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
15af0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
15b00 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
15b10 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
15b20 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
15b30 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
15b40 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
15b50 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
15b60 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
15b70 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
15b80 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
15b90 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
15ba0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
15bb0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15bc0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
15bd0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
15be0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
15bf0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15c00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
15c10 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
15c20 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
15c30 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
15c40 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15c50 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15c60 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
15c70 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
15c80 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
15c90 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
15ca0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
15cb0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
15cc0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
15cd0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
15ce0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15cf0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
15d00 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
15d10 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
15d20 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
15d30 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
15d40 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
15d50 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
15d60 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
15d70 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15d80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15d90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
15da0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
15db0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
15dc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15dd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
15de0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
15df0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
15e00 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
15e10 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
15e20 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
15e30 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
15e40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15e50 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
15e60 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
15e70 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
15e80 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
15e90 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15ea0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
15eb0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
15ec0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
15ed0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
15ee0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
15ef0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
15f00 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
15f10 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
15f20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
15f30 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
15f40 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
15f50 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
15f60 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
15f70 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
15f80 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
15f90 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
15fa0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
15fb0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
15fc0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
15fd0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
15fe0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
15ff0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
16000 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
16010 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
16020 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
16030 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
16040 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
16050 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
16060 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16070 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
16080 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
16090 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
160a0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
160b0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
160c0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
160d0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
160e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
160f0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
16100 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16110 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
16120 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
16130 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
16140 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
16150 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
16160 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
16170 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
16180 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
16190 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
161a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
161b0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
161c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
161d0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
161e0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
161f0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
16200 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
16210 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
16220 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
16230 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
16240 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
16250 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
16260 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
16270 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
16280 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
16290 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
162a0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
162b0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
162c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
162d0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
162e0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
162f0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
16300 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
16310 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
16320 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
16330 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
16340 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
16350 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
16360 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
16370 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
16380 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
16390 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
163a0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
163b0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
163c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
163d0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
163e0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
163f0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
16400 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
16410 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
16420 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
16430 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
16440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16450 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
16460 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
16470 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
16480 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
16490 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
164a0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
164b0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
164c0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
164d0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
164e0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
164f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
16500 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16510 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
16520 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
16530 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
16540 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
16550 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
16560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
16570 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
16580 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
16590 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
165a0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
165b0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
165c0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
165d0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
165e0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
165f0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
16600 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
16610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
16620 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16630 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16640 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16650 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16660 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16670 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16680 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16690 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
166a0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
166b0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
166c0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
166d0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
166e0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
166f0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16700 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16710 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16720 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16730 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16740 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16750 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16760 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16770 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16780 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16790 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
167a0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
167b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
167c0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
167d0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
167e0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
167f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16800 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
16810 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
16820 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
16830 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
16840 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
16850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16860 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
16870 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
16880 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
16890 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
168a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
168b0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
168c0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
168d0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
168e0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
168f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
16900 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
16910 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
16920 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
16930 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
16940 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
16950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
16960 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
16970 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16980 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16990 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
169a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
169b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
169c0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
169d0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
169e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
169f0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
16a00 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
16a10 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
16a20 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
16a30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16a40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
16a50 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
16a60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
16a70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
16a80 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
16a90 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
16aa0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
16ab0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
16ac0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
16ad0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
16ae0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
16af0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
16b00 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
16b10 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
16b20 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
16b30 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
16b40 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
16b50 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
16b60 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
16b70 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
16b80 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
16b90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16ba0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
16bb0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
16bc0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
16bd0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
16be0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
16bf0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
16c00 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
16c10 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16c20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
16c30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16c40 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
16c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
16c60 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
16c70 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
16c80 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
16c90 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
16ca0 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
16cb0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
16cc0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
16cd0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
16ce0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
16cf0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
16d00 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
16d10 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
16d20 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
16d30 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
16d40 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
16d50 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
16d60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
16d70 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
16d80 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
16d90 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
16da0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
16db0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
16dc0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
16dd0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
16de0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
16df0 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
16e00 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
16e10 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
16e20 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
16e30 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
16e40 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
16e50 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
16e60 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
16e70 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
16e80 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
16e90 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
16ea0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
16eb0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
16ec0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
16ed0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
16ee0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16ef0 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
16f00 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
16f10 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
16f20 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
16f30 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
16f40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
16f50 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
16f60 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
16f70 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
16f80 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
16f90 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
16fa0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16fb0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
16fc0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
16fd0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
16fe0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
16ff0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
17000 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17010 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17020 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
17030 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
17040 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
17050 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
17060 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
17070 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
17080 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
17090 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
170a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
170b0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
170c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
170d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
170e0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
170f0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
17100 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
17110 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
17120 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
17130 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
17140 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
17150 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
17160 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
17170 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
17180 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
17190 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
171a0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
171b0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
171c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
171d0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
171e0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
171f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17200 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
17210 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
17220 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
17230 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
17240 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
17250 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17260 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
17270 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17280 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
17290 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
172a0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
172b0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
172c0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
172d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
172e0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
172f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
17300 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
17310 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
17320 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
17330 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
17340 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
17350 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
17360 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
17370 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
17380 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
17390 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
173a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
173b0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
173c0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
173d0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
173e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
173f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17400 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
17410 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
17420 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
17430 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
17440 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
17450 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
17460 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
17470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
17480 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
17490 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
174a0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
174b0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
174c0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
174d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
174e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
174f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17500 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
17510 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
17520 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
17530 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
17540 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
17550 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
17560 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
17570 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
17580 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17590 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
175a0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
175b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
175c0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
175d0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
175e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
175f0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
17600 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
17610 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
17620 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
17630 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
17640 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
17650 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
17660 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
17670 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
17680 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
17690 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
176a0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
176b0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
176c0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
176d0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
176e0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
176f0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
17700 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
17710 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
17720 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
17730 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
17740 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
17750 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
17760 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
17770 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
17780 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
17790 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
177a0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
177b0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
177c0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
177d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
177e0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
177f0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
17800 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
17810 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
17820 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
17830 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
17840 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
17850 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
17860 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
17870 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
17880 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
17890 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
178a0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
178b0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
178c0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
178d0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
178e0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
178f0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
17900 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
17910 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
17920 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
17930 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
17940 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
17950 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
17960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17970 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
17980 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
17990 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
179a0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
179b0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
179c0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
179d0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
179e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
179f0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
17a00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
17a10 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
17a20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17a30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
17a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17a50 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
17a60 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
17a70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
17a80 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
17a90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17aa0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
17ab0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
17ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17ad0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
17ae0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
17af0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
17b00 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
17b10 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
17b20 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
17b30 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
17b40 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
17b50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17b60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
17b70 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
17b80 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
17b90 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
17ba0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
17bb0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
17bc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
17bd0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
17be0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17bf0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
17c00 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
17c10 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
17c20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17c30 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
17c40 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
17c50 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
17c60 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
17c70 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
17c80 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
17c90 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
17ca0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
17cb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17cc0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
17cd0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
17ce0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
17cf0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
17d00 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
17d10 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
17d20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17d30 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17d40 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
17d50 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
17d60 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
17d70 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
17d80 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
17d90 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
17da0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
17db0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
17dc0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17dd0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
17de0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
17df0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17e00 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
17e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17e20 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
17e30 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
17e40 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
17e50 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17e60 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17e70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17e80 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17e90 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17ea0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
17eb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17ec0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17ed0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17ee0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
17ef0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
17f00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
17f10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
17f20 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
17f30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
17f40 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
17f50 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
17f60 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17f70 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17f80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
17f90 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
17fa0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17fb0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
17fc0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
17fd0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
17fe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
17ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18000 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
18010 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
18020 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
18030 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
18040 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
18050 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
18060 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
18070 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
18080 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
18090 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
180a0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
180b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
180c0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
180d0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
180e0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
180f0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
18100 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
18110 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
18120 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
18130 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
18140 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
18150 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
18160 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
18170 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
18180 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
18190 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
181a0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
181b0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
181c0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
181d0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
181e0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
181f0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
18200 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18210 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18220 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
18230 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
18240 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
18250 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
18260 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
18270 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
18280 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
18290 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
182a0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
182b0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
182c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
182d0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
182e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
182f0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
18300 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
18310 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
18320 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
18330 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
18340 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
18350 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
18360 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
18370 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
18380 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
18390 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
183a0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
183b0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
183c0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
183d0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
183e0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
183f0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
18400 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
18410 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
18420 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
18430 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
18440 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
18450 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
18460 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
18470 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
18480 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
18490 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
184a0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
184b0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
184c0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
184d0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
184e0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
184f0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
18500 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
18510 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
18520 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
18530 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
18540 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
18550 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
18560 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
18570 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
18580 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
18590 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
185a0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
185b0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
185c0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
185d0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
185e0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
185f0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
18600 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
18610 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
18620 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
18630 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
18640 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
18650 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
18660 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
18670 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
18680 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
18690 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
186a0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
186b0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
186c0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
186d0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
186e0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
186f0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
18700 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
18710 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18720 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
18730 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
18740 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
18750 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
18760 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
18770 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
18780 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
18790 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
187a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
187b0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
187c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
187d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
187e0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
187f0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
18800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18810 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
18820 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
18830 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
18840 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
18850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18860 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
18870 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
18880 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
18890 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
188a0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
188b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
188c0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
188d0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
188e0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
188f0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
18900 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
18910 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
18920 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
18930 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
18940 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
18950 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
18960 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
18970 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18980 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18990 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
189a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
189b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
189c0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
189d0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
189e0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
189f0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
18a00 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
18a10 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
18a20 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
18a30 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
18a40 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
18a50 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
18a60 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
18a70 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
18a80 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
18a90 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
18aa0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
18ab0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18ac0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18ad0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18ae0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
18af0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18b00 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18b10 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
18b20 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
18b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18b40 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
18b50 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
18b60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
18b70 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
18b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18b90 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
18ba0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
18bb0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
18bc0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
18bd0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
18be0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
18bf0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
18c00 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
18c10 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
18c20 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
18c30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18c40 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18c50 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
18c60 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
18c70 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
18c80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18c90 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
18ca0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
18cb0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
18cc0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
18cd0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
18ce0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
18cf0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
18d00 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
18d10 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
18d20 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
18d30 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
18d40 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
18d50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18d60 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
18d70 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
18d80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
18d90 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
18da0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
18db0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
18dc0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
18dd0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
18de0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
18df0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18e00 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
18e10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
18e20 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
18e30 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
18e40 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
18e50 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
18e60 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
18e70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18e80 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
18e90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
18ea0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
18eb0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
18ec0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
18ed0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
18ee0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
18ef0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
18f00 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
18f10 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
18f20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
18f30 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18f40 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18f50 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
18f60 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
18f70 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
18f80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
18f90 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
18fa0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18fb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18fc0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18fe0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18ff0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
19000 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
19010 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
19020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19030 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
19040 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
19050 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
19060 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
19070 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
19080 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
19090 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
190a0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
190b0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
190c0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
190d0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
190e0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
190f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
19110 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
19120 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
19130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19140 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
19150 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
19160 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19170 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19180 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19190 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
191a0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
191b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
191c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
191d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
191e0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
191f0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
19200 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19210 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19220 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19230 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
19240 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
19250 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19260 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19270 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19280 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
19290 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
192a0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
192b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
192c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
192d0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
192e0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
192f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19300 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19310 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
19320 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
19330 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
19340 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
19350 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19360 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
19370 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
19380 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19390 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
193a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
193b0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
193c0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
193d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
193e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
193f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19400 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
19410 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
19420 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19430 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19440 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19450 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
19460 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
19470 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19480 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
194a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
194b0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
194c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
194d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
194e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
19500 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
19510 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19520 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19540 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
19550 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
19560 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19590 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
195a0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
195b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
195c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
195d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
195e0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
195f0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
19600 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19610 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19630 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
19640 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
19650 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
19660 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
19680 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
19690 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
196a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
196b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
196c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
196d0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
196e0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
196f0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
19700 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
19710 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
19720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19730 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
19740 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19750 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19760 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
19770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19780 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
19790 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
197a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
197b0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
197c0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
197d0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
197e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
197f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19800 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
19810 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
19820 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19830 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
19840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19850 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
19860 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
19870 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
19880 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
198a0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
198b0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
198c0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
198d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
198e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
198f0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
19900 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
19910 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
19920 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19940 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
19950 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
19960 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19990 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
199a0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
199b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
199c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
199d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199e0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
199f0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
19a00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
19a10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19a30 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
19a40 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
19a50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
19a60 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
19a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a80 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
19a90 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
19aa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
19ab0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
19ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19ad0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
19ae0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
19af0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
19b00 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
19b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19b20 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
19b30 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
19b40 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
19b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
19b60 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
19b70 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
19b80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19b90 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
19ba0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
19bb0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
19bc0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
19bd0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
19be0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
19bf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
19c00 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
19c10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19c20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19c30 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
19c40 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
19c50 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
19c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
19c70 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
19c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
19c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19ca0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
19cb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
19cc0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19cd0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
19ce0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19cf0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19d00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19d10 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
19d20 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
19d30 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19d40 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
19d50 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19d60 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
19d70 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
19d80 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
19d90 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
19da0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
19db0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
19dc0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19dd0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
19de0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19df0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19e00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19e10 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19e20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
19e30 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
19e40 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19e50 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19e60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19e70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19e80 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19e90 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19ea0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
19eb0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
19ec0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
19ed0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19ee0 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
19ef0 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
19f00 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
19f10 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
19f20 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
19f30 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
19f40 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
19f50 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
19f60 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
19f70 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
19f80 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
19f90 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
19fa0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
19fb0 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
19fc0 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
19fd0 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
19fe0 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
19ff0 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1a000 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1a010 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1a020 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1a030 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1a040 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1a050 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1a060 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1a070 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1a080 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1a090 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1a0a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1a0b0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1a0c0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1a0d0 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1a0e0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1a0f0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1a100 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1a110 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1a120 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a130 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1a140 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1a150 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1a160 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a170 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1a180 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1a190 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1a1a0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1a1b0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1a1c0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1a1d0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1a1e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1a1f0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1a200 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1a210 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a220 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1a230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a240 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1a250 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1a260 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1a270 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1a280 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1a290 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1a2a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1a2b0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1a2c0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1a2d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1a2e0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1a2f0 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1a300 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1a310 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1a320 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1a330 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1a340 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1a350 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1a360 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1a370 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1a380 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1a390 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1a3a0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1a3b0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1a3c0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1a3d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a3e0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1a3f0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1a400 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1a410 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1a420 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1a430 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1a440 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1a450 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1a460 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a470 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1a480 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1a490 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1a4a0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1a4b0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1a4c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a4d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1a4e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1a4f0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1a500 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1a510 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1a520 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1a530 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1a540 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1a550 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1a560 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a570 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1a580 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1a590 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1a5a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1a5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1a5c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1a5d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1a5e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1a5f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a600 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1a610 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1a620 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1a630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a640 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1a650 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1a660 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1a670 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1a680 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a690 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a6a0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1a6b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1a6c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1a6d0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1a6e0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1a6f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1a700 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1a710 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1a720 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
1a730 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
1a740 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1a750 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1a760 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1a770 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1a780 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1a790 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a7a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1a7b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1a7c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1a7d0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1a7e0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1a7f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a800 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1a810 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1a820 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1a830 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1a840 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1a850 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1a860 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1a870 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1a880 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1a890 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1a8a0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1a8b0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1a8c0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1a8d0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1a8e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1a8f0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1a900 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1a910 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1a920 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1a930 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1a940 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1a950 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1a960 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1a970 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1a980 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1a990 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1a9a0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1a9b0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1a9c0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1a9d0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1a9e0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1a9f0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1aa00 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1aa10 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1aa20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1aa30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1aa40 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1aa50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1aa60 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1aa70 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1aa80 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1aa90 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1aaa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1aab0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1aac0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1aad0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1aae0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1aaf0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1ab00 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1ab10 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1ab20 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1ab30 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1ab40 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1ab50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1ab60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ab70 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1ab80 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1ab90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1aba0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1abb0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1abc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1abd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1abe0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1abf0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1ac00 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1ac10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1ac20 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1ac30 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1ac40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1ac50 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1ac60 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1ac70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1ac80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1ac90 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1aca0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1acb0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1acc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1acd0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1ace0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1acf0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1ad00 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1ad10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1ad20 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1ad30 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1ad40 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  HE],.** and/or [
1ad50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1ad60 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a  ATECACHE] flags:
1ad70 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1ad80 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1ad90 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1ada0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1adb0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1adc0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1add0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1ade0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1adf0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1ae00 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1ae10 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1ae20 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1ae30 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ae40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ae50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ae60 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1ae70 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1ae80 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1ae90 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1aea0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1aeb0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1aec0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1aed0 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1aee0 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1aef0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1af00 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1af10 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1af20 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1af30 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1af40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1af50 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1af60 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1af70 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1af80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1af90 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1afa0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1afb0 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
1afc0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1afd0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1afe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1aff0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1b000 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1b010 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1b020 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1b030 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1b040 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1b050 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b060 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1b070 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1b080 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1b090 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1b0a0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1b0b0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1b0c0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1b0d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1b0e0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1b0f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1b100 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1b110 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1b120 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1b130 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1b140 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1b150 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1b160 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1b170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1b180 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b190 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1b1a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1b1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b1c0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1b1d0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1b1e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1b1f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1b200 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1b210 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1b220 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1b230 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1b240 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1b250 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1b260 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1b270 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1b280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1b290 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1b2a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1b2b0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1b2c0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1b2d0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1b2e0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1b2f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1b300 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1b310 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1b320 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1b330 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1b340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b350 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1b360 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1b370 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1b380 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1b390 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1b3a0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1b3b0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1b3c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1b3d0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1b3e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1b3f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1b400 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1b410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b420 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1b430 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1b440 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1b450 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1b460 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1b470 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b480 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1b490 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1b4a0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1b4b0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1b4c0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1b4d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1b4e0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1b4f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1b500 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1b510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b520 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1b530 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1b540 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1b550 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1b560 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1b570 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1b580 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1b590 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1b5a0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1b5b0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1b5c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1b5d0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1b5e0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1b5f0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1b600 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1b610 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1b620 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1b630 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1b640 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1b650 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1b660 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1b670 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1b680 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1b690 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1b6a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b6b0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1b6c0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1b6d0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1b6e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1b6f0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1b700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b710 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1b720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1b730 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1b740 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b750 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1b760 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1b770 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1b780 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1b790 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1b7a0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1b7b0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1b7c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1b7d0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1b7e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b7f0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1b800 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1b810 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1b820 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1b830 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1b840 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1b850 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1b860 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1b870 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1b880 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1b890 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1b8a0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1b8b0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1b8c0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1b8d0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1b8e0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1b8f0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1b900 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1b910 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1b920 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1b930 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1b940 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1b950 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1b960 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1b970 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b990 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1b9a0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1b9b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1b9c0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1b9d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1b9e0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1b9f0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1ba00 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1ba10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1ba20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1ba30 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1ba40 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1ba50 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1ba60 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1ba70 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1ba80 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1ba90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1baa0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1bab0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1bac0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1bad0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1bae0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1baf0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1bb00 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1bb10 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1bb20 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1bb30 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1bb40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1bb50 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1bb60 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1bb70 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1bb80 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1bb90 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1bba0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1bbb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1bbc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1bbd0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1bbe0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1bbf0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bc00 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1bc10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1bc20 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1bc30 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1bc40 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1bc50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bc60 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1bc70 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1bc80 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1bc90 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1bca0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1bcb0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1bcc0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1bcd0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1bce0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1bcf0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1bd00 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1bd10 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1bd20 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1bd30 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1bd40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bd50 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1bd60 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1bd70 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1bd80 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1bd90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1bda0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1bdb0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1bdc0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1bdd0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1bde0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1bdf0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1be00 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1be10 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1be20 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1be30 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1be40 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1be50 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1be60 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1be70 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1be80 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1be90 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1bea0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1beb0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1bec0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1bed0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1bee0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1bef0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bf00 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1bf10 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1bf20 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1bf30 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1bf40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1bf50 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1bf60 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1bf70 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1bf80 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1bf90 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1bfa0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1bfb0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1bfc0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1bfd0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1bfe0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1bff0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1c000 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1c010 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1c020 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1c030 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1c040 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1c050 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c060 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1c070 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1c080 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1c090 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1c0a0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1c0b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1c0c0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1c0d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1c0e0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1c0f0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1c100 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1c110 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1c120 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1c130 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1c140 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1c150 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1c160 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1c170 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1c180 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1c190 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1c1a0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1c1b0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1c1c0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1c1d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1c1e0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1c1f0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1c200 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1c210 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1c220 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1c230 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1c240 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1c250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1c260 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1c270 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1c280 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1c290 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1c2a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1c2b0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1c2c0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1c2d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1c2e0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1c2f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1c300 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1c310 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1c320 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1c330 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1c340 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1c350 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1c360 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1c370 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1c380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1c390 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1c3a0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1c3b0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1c3c0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1c3d0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1c3e0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1c3f0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1c400 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1c410 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1c420 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1c430 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1c440 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1c450 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1c460 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1c470 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1c480 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1c490 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1c4a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1c4b0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1c4c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1c4d0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1c4e0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1c4f0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1c500 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1c510 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1c520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c530 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1c540 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1c550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1c560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1c570 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1c580 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1c590 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1c5a0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1c5b0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1c5c0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1c5d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1c5e0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1c5f0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1c600 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1c610 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1c620 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1c630 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1c640 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1c650 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1c660 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1c670 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1c680 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1c690 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1c6a0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1c6b0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1c6c0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1c6d0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1c6e0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1c6f0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1c700 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1c710 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c720 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1c730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c740 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1c750 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1c760 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1c770 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c780 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1c790 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1c7a0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1c7b0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1c7c0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1c7d0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1c7e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1c7f0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1c800 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1c810 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
1c820 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1c830 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1c840 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1c850 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1c860 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
1c870 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
1c880 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
1c890 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
1c8a0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1c8b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1c8c0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
1c8d0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
1c8e0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1c8f0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
1c900 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1c910 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
1c920 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1c930 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1c940 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1c950 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
1c960 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
1c970 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
1c980 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1c990 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
1c9a0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
1c9b0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
1c9c0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
1c9d0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1c9e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
1c9f0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
1ca00 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1ca10 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
1ca20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1ca30 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
1ca40 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
1ca50 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
1ca60 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1ca70 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
1ca80 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
1ca90 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
1caa0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
1cab0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
1cac0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
1cad0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
1cae0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
1caf0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
1cb00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1cb10 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
1cb20 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
1cb30 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
1cb40 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
1cb50 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
1cb60 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
1cb70 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
1cb80 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
1cb90 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
1cba0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
1cbb0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
1cbc0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1cbd0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1cbe0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1cbf0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1cc00 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1cc10 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1cc20 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1cc30 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1cc40 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1cc50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1cc60 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1cc70 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1cc80 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1cc90 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1cca0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ccb0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1ccc0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1ccd0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1cce0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1ccf0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1cd00 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
1cd10 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1cd20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1cd30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1cd40 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1cd50 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1cd60 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1cd70 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1cd80 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1cd90 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1cda0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1cdb0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1cdc0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1cdd0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1cde0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1cdf0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
1ce00 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
1ce10 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
1ce20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1ce30 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
1ce40 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1ce50 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1ce60 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1ce70 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1ce80 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1ce90 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
1cea0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1ceb0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
1cec0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
1ced0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
1cee0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
1cef0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
1cf00 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
1cf10 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
1cf20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1cf30 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1cf40 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
1cf50 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1cf60 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
1cf70 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
1cf80 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
1cf90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
1cfa0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
1cfb0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
1cfc0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
1cfd0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cfe0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
1cff0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d000 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
1d010 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
1d020 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
1d030 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
1d040 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d050 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1d060 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d070 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1d080 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1d090 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
1d0a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d0b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d0c0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1d0d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d0e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1d0f0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1d100 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1d110 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1d120 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
1d130 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1d140 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1d150 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1d160 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1d170 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1d180 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
1d190 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d1a0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1d1b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d1c0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1d1d0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1d1e0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1d1f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d200 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d210 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1d220 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1d230 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d240 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1d250 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1d260 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1d270 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d280 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1d290 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1d2a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d2b0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1d2c0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1d2d0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1d2e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d2f0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1d300 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
1d310 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
1d320 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
1d330 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
1d340 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
1d350 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
1d360 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
1d370 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d380 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1d390 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1d3a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d3b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1d3c0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1d3d0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
1d3e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d3f0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1d400 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d410 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1d420 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1d430 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1d440 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28  )^</dd>.**.** ^(
1d450 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d460 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1d470 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d480 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1d490 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1d4a0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1d4b0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
1d4c0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
1d4d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d4e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d4f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d500 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1d510 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
1d520 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
1d530 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
1d540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
1d550 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d560 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1d570 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1d580 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d590 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
1d5a0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
1d5b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1d5c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1d5d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1d5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d5f0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1d600 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1d610 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1d620 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1d630 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1d640 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1d650 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1d660 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1d670 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1d680 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1d690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1d6a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1d6b0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1d6c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1d6d0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1d6e0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1d6f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1d700 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1d710 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1d720 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d730 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1d740 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1d750 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d760 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1d770 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1d780 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d790 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d7a0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1d7b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d7c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1d7d0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1d7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d7f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1d800 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
1d810 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1d820 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1d830 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1d840 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1d850 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1d860 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1d870 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1d880 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1d890 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1d8a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1d8b0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1d8c0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1d8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1d8e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1d8f0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
1d900 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1d910 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1d920 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1d930 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
1d940 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
1d950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d960 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
1d970 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
1d980 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1d990 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1d9a0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1d9b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1d9c0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1d9d0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1d9e0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1d9f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1da00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1da10 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1da20 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1da30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1da40 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1da50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1da60 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1da70 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
1da80 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1da90 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1daa0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1dab0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1dac0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1dad0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
1dae0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1daf0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1db00 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1db10 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1db20 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1db30 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
1db40 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1db50 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1db60 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1db70 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1db80 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1db90 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1dba0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1dbb0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1dbc0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1dbd0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1dbe0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1dbf0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1dc00 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1dc10 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1dc20 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1dc30 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1dc40 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1dc50 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1dc60 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1dc70 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1dc80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1dc90 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1dca0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1dcb0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1dcc0 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
1dcd0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
1dce0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
1dcf0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1dd00 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1dd10 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
1dd20 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1dd30 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1dd40 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1dd50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1dd60 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
1dd70 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
1dd80 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1dd90 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1dda0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
1ddb0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
1ddc0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
1ddd0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1dde0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1ddf0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1de00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1de10 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1de20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1de30 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
1de40 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1de50 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1de60 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
1de70 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1de80 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1de90 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1dea0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1deb0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1dec0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1ded0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1dee0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
1def0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1df00 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1df10 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1df20 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1df30 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1df40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1df50 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1df60 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
1df70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
1df80 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
1df90 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
1dfa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1dfb0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
1dfc0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1dfd0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
1dfe0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1dff0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1e000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1e010 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1e020 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e030 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1e040 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1e050 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1e060 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1e070 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1e080 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1e090 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1e0a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1e0b0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1e0c0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1e0d0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
1e0e0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1e0f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1e100 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1e110 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1e120 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1e130 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1e140 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1e150 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1e160 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1e170 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1e180 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1e190 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
1e1a0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
1e1b0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1e1c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1e1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1e1e0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1e1f0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1e200 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1e210 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1e220 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1e230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1e240 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1e250 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1e260 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1e270 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1e280 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
1e290 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1e2a0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1e2b0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1e2c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1e2d0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1e2e0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1e2f0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1e300 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1e310 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1e320 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1e330 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1e340 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1e350 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1e360 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1e370 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1e380 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1e390 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1e3a0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1e3b0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1e3c0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1e3d0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1e3e0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1e3f0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1e400 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1e410 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1e420 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1e430 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1e440 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1e450 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1e460 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1e470 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1e480 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
1e490 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
1e4a0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1e4b0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1e4c0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
1e4d0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
1e4e0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
1e4f0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
1e500 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
1e510 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1e520 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
1e530 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1e540 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
1e550 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
1e560 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
1e570 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
1e580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1e590 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1e5a0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
1e5b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1e5c0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
1e5d0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
1e5e0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
1e5f0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
1e600 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
1e610 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
1e620 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
1e630 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
1e640 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
1e650 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
1e660 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
1e670 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
1e680 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
1e690 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
1e6a0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
1e6b0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
1e6c0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
1e6d0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
1e6e0 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT2] compile-ti
1e6f0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
1e700 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
1e710 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
1e720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1e730 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1e740 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e750 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e760 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e770 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e780 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e790 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1e7a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e7b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e7c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e7d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e7e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e7f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e800 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e810 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e820 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1e830 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e840 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e850 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e860 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1e880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e890 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1e8a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1e8b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1e8c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1e8d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1e8e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e8f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e900 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e910 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e920 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e930 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e940 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e950 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e960 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e970 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e980 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e990 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e9a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1e9b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e9c0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1e9d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1e9e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1e9f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1ea00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1ea10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1ea20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1ea30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ea40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ea50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ea60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1ea70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1ea80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1ea90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1eaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1eab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1eac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1ead0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1eae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1eaf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1eb00 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1eb10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1eb20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1eb30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1eb40 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1eb50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1eb60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1eb70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1eb80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1eb90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1eba0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1ebb0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1ebc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1ebd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1ebe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1ebf0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1ec00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1ec10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1ec20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1ec30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1ec40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1ec50 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1ec60 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
1ec70 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1ec80 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1ec90 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1eca0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1ecb0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1ecc0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1ecd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ece0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1ecf0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1ed00 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1ed10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ed20 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1ed30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ed40 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
1ed50 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1ed60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1ed70 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1ed80 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
1ed90 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
1eda0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1edb0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1edc0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1edd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ede0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1edf0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1ee00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ee10 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1ee20 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1ee30 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1ee40 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1ee50 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1ee60 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1ee70 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1ee80 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
1ee90 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
1eea0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1eeb0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
1eec0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
1eed0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1eee0 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
1eef0 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
1ef00 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
1ef10 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
1ef20 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
1ef30 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
1ef40 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
1ef50 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1ef60 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1ef70 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
1ef80 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1ef90 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
1efa0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
1efb0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1efc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1efd0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
1efe0 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
1eff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
1f000 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
1f010 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
1f020 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
1f030 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1f040 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
1f050 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
1f060 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
1f070 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
1f080 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
1f090 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
1f0a0 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61  held.  A interna
1f0b0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
1f0c0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
1f0d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1f0e0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
1f0f0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1f100 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
1f110 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1f120 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
1f130 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1f140 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
1f150 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
1f160 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1f170 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
1f180 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1f190 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
1f1a0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
1f1b0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
1f1c0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
1f1d0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
1f1e0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1f1f0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
1f200 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
1f210 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
1f220 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
1f230 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
1f240 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1f250 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1f260 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f270 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
1f280 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
1f290 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
1f2a0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
1f2b0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
1f2c0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
1f2d0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1f2e0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
1f2f0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
1f300 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1f310 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1f320 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1f330 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1f340 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
1f350 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
1f360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f370 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1f380 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
1f390 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
1f3a0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
1f3b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
1f3c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1f3d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1f3e0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1f3f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f400 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1f410 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1f420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1f430 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1f440 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1f450 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1f460 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1f470 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1f480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1f490 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1f4a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1f4b0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
1f4c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1f4d0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
1f4e0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
1f4f0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
1f500 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
1f510 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f520 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1f530 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1f540 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1f550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f560 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
1f570 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
1f580 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
1f590 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
1f5a0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
1f5b0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
1f5c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
1f5d0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
1f5e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
1f5f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1f600 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
1f610 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
1f620 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
1f630 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1f640 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
1f650 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
1f660 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1f670 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
1f680 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
1f690 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
1f6a0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
1f6b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
1f6c0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
1f6d0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
1f6e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
1f6f0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
1f700 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
1f710 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f720 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
1f730 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
1f740 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
1f750 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
1f760 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
1f770 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1f780 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
1f790 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
1f7a0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
1f7b0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
1f7c0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
1f7d0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
1f7e0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
1f7f0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
1f800 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
1f810 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
1f820 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1f830 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
1f840 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
1f850 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
1f860 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
1f870 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1f880 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
1f890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f8a0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
1f8b0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
1f8c0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
1f8d0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
1f8e0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
1f8f0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
1f900 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
1f910 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
1f920 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
1f930 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
1f940 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
1f950 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
1f960 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
1f970 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
1f980 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
1f990 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
1f9a0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
1f9b0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
1f9c0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
1f9d0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
1f9e0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
1f9f0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
1fa00 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
1fa10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1fa20 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
1fa30 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
1fa40 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
1fa50 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fa60 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
1fa70 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
1fa80 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1fa90 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1faa0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1fab0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1fac0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1fad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1fae0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1faf0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1fb00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1fb10 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1fb20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
1fb30 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1fb40 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1fb50 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1fb60 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
1fb70 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1fb80 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1fb90 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
1fba0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1fbb0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1fbc0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1fbd0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1fbe0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1fbf0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1fc00 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1fc10 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1fc20 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1fc30 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
1fc40 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1fc50 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1fc60 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1fc70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fc80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
1fc90 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1fca0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
1fcb0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
1fcc0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
1fcd0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
1fce0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
1fcf0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
1fd00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
1fd10 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
1fd20 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
1fd30 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1fd40 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
1fd50 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
1fd60 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1fd70 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
1fd80 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
1fd90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1fda0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
1fdb0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1fdc0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1fdd0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1fde0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1fdf0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1fe00 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1fe10 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1fe20 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1fe30 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1fe40 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1fe50 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1fe60 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
1fe70 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1fe80 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
1fe90 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
1fea0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
1feb0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
1fec0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
1fed0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1fee0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1fef0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
1ff00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1ff10 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1ff20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1ff30 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1ff40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1ff50 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1ff60 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1ff70 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1ff80 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1ff90 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1ffa0 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20 74  d with it. ^If t
1ffb0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1ffc0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
1ffd0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
1ffe0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
1fff0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
20000 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
20010 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
20020 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
20030 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
20040 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
20050 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
20060 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
20070 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
20080 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
20090 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
200a0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
200b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
200c0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
200d0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
200e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
200f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20100 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
20110 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
20120 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
20130 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
20140 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
20150 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
20160 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
20170 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
20180 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
20190 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
201a0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
201b0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
201c0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
201d0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
201e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
201f0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
20200 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
20210 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
20220 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
20230 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
20240 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
20250 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
20260 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
20270 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
20280 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
20290 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
202a0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
202b0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
202c0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
202d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
202e0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
202f0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
20300 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
20310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20320 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
20330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20340 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
20350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
20360 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
20370 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
20380 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
20390 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
203a0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
203b0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
203c0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
203d0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
203e0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
203f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
20400 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
20410 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
20420 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
20430 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
20440 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
20450 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
20460 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
20470 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
20480 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
20490 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
204a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
204b0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
204c0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
204d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
204e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
204f0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
20500 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
20510 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
20520 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
20530 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
20540 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
20550 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
20560 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
20570 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
20580 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
20590 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
205a0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
205b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
205c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
205d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
205e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
205f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
20600 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
20610 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
20620 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
20630 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20650 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
20660 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
20670 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20680 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
20690 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
206a0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
206b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
206c0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
206d0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
206e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
206f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
20700 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
20710 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
20720 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
20730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20740 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
20750 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
20760 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
20770 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
20780 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
20790 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
207a0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
207b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
207c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
207d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
207e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
207f0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
20800 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
20810 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
20820 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
20830 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
20840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20850 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
20860 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
20870 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
20880 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
20890 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
208a0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
208b0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
208c0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
208d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
208e0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
208f0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
20900 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
20910 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
20920 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
20930 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
20940 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
20950 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
20960 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
20970 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
20980 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
20990 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
209a0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
209b0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
209c0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
209d0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
209e0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
209f0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
20a00 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
20a10 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
20a20 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
20a30 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
20a40 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
20a50 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
20a60 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
20a70 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
20a80 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
20a90 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
20aa0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
20ab0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
20ac0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
20ad0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
20ae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
20af0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
20b00 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
20b10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20b20 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
20b30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20b40 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
20b50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
20b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20b70 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
20b80 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
20b90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
20ba0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20bb0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
20bc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
20bd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
20be0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
20bf0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20c00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
20c10 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
20c20 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
20c30 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
20c40 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
20c50 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
20c60 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
20c70 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
20c80 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
20c90 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
20ca0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
20cb0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
20cc0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
20cd0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
20ce0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
20cf0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
20d00 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
20d10 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
20d20 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
20d30 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
20d40 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
20d50 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
20d60 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
20d70 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
20d80 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
20d90 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
20da0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
20db0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
20dc0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
20dd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
20de0 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
20df0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
20e00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
20e10 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
20e20 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
20e30 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
20e40 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
20e50 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
20e60 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
20e70 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
20e80 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
20e90 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
20ea0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
20eb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20ec0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
20ed0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20ee0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
20ef0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
20f00 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
20f10 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
20f20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20f30 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
20f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20f50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20f60 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
20f70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
20f80 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
20f90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20fa0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
20fb0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
20fc0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
20fd0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
20fe0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
20ff0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
21000 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
21010 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
21020 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
21030 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
21040 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
21050 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
21060 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
21070 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
21080 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
21090 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
210a0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
210b0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
210c0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
210d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
210e0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
210f0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
21100 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
21110 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
21120 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
21130 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
21140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21150 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
21160 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21170 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
21180 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
21190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
211a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
211b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
211c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
211d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
211e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
211f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
21200 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
21210 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
21220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21230 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
21240 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
21250 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
21260 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
21270 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
21280 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
21290 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
212a0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
212b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
212c0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
212d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
212e0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
212f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
21300 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
21310 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
21320 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
21330 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
21340 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
21350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21360 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
21370 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
21380 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
21390 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
213a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
213b0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
213c0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
213d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
213e0 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
213f0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
21400 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
21410 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
21420 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
21430 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
21440 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
21450 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
21460 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
21470 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
21480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
21490 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
214a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
214b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
214c0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
214d0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
214e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
214f0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
21500 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
21510 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
21520 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
21530 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
21540 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
21550 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
21560 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
21570 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
21580 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
21590 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
215a0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
215b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
215c0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
215d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
215e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
215f0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
21600 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
21610 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
21620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21630 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
21640 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
21650 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
21660 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21670 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
21680 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
21690 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
216a0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
216b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
216c0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
216d0 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
216e0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
216f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21700 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
21710 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
21720 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
21730 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
21740 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
21750 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
21760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
21770 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
21780 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
21790 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
217a0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
217b0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
217c0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
217d0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
217e0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
217f0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
21800 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
21810 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
21820 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
21830 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
21840 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
21850 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
21860 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
21870 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
21880 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
21890 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
218a0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
218b0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
218c0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
218d0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
218e0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
218f0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
21900 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
21910 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
21920 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
21930 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
21940 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
21950 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
21960 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
21970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
21980 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21990 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
219a0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
219b0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
219c0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
219d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
219e0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
219f0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
21a00 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
21a10 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
21a20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
21a30 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
21a40 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
21a50 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
21a60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
21a70 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
21a80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
21a90 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
21aa0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
21ab0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
21ac0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
21ad0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
21ae0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
21af0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
21b00 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
21b10 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
21b20 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
21b30 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
21b40 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
21b50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
21b60 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
21b70 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
21b80 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
21b90 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
21ba0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21bb0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
21bc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
21bd0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
21be0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
21bf0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
21c00 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
21c10 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
21c20 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
21c30 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
21c40 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
21c50 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
21c60 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
21c70 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
21c80 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
21c90 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
21ca0 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
21cb0 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
21cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21cd0 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
21ce0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
21cf0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
21d00 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
21d10 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
21d20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
21d30 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
21d40 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
21d50 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
21d60 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
21d70 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
21d80 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
21d90 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
21da0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
21db0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
21dc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
21dd0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
21de0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
21df0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
21e00 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
21e10 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
21e20 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
21e30 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
21e40 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
21e50 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
21e60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
21e70 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
21e80 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
21e90 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
21ea0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
21eb0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
21ec0 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
21ed0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
21ee0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
21ef0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
21f00 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
21f10 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
21f20 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
21f30 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
21f40 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
21f50 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
21f60 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
21f70 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
21f80 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
21f90 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
21fa0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
21fb0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
21fc0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
21fd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
21fe0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
21ff0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
22000 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
22010 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
22020 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
22030 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
22040 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
22050 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
22060 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
22070 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
22080 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
22090 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
220a0 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
220b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
220c0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
220d0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
220e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
220f0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
22100 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
22110 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
22120 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
22130 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22140 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
22150 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
22160 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
22170 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22180 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
22190 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
221a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
221b0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
221c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
221d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
221e0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
221f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
22200 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
22210 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22220 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
22230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
22240 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
22250 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22260 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
22270 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22280 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
222a0 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
222b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
222c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
222d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
222e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
222f0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
22300 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
22310 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
22320 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
22330 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
22340 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
22350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22360 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
22370 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
22380 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
22390 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
223a0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
223b0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
223c0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
223d0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
223e0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
223f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
22400 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
22410 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
22420 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
22430 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
22440 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
22450 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
22460 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
22470 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
22480 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
22490 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
224a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
224b0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
224c0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
224d0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
224e0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
224f0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
22500 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
22510 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
22520 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
22530 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
22540 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
22550 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
22560 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
22570 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
22580 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
22590 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
225a0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
225b0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
225c0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
225d0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
225e0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
225f0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
22600 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
22610 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
22620 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
22630 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
22640 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
22650 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
22660 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
22670 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
22680 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
22690 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
226a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
226b0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
226c0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
226d0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
226e0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
226f0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
22700 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
22710 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
22720 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
22730 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
22740 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
22750 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
22760 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
22770 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
22780 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
22790 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
227a0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
227b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
227c0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
227d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
227e0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
227f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
22800 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
22810 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
22820 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
22830 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
22840 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
22850 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
22860 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
22870 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22880 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
22890 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
228a0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
228b0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
228c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
228d0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
228e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
228f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
22900 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
22910 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
22920 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
22930 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
22940 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
22950 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
22960 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
22970 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
22980 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
22990 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
229a0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
229b0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
229c0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
229d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
229e0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
229f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22a00 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
22a10 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
22a20 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
22a30 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
22a40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22a50 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
22a60 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
22a70 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
22a80 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
22a90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
22aa0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
22ab0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
22ac0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
22ad0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
22ae0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
22af0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
22b00 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
22b10 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
22b20 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
22b30 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
22b40 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
22b50 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
22b60 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
22b70 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
22b80 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
22b90 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
22ba0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
22bb0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
22bc0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
22bd0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
22be0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
22bf0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
22c00 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
22c10 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
22c20 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
22c30 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
22c40 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
22c50 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
22c60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
22c70 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
22c80 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
22c90 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
22ca0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
22cb0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
22cc0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
22cd0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
22ce0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
22cf0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
22d00 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
22d10 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
22d20 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
22d30 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
22d40 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
22d50 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
22d60 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
22d70 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
22d80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
22d90 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
22da0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
22db0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
22dc0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
22dd0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
22de0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
22df0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
22e00 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
22e10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
22e20 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
22e30 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
22e40 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
22e50 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
22e60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
22e70 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
22e80 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
22e90 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
22ea0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
22eb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
22ec0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
22ed0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
22ee0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
22ef0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
22f00 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
22f10 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
22f20 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
22f30 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
22f40 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
22f50 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
22f60 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
22f70 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
22f80 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
22f90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
22fa0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
22fb0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
22fc0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
22fd0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
22fe0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
22ff0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
23000 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
23010 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
23020 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
23030 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
23040 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
23050 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
23060 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
23070 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
23080 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
23090 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
230a0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
230b0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
230c0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
230d0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
230e0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
230f0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
23100 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
23110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23120 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
23130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23140 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
23150 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
23160 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
23170 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
23180 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
23190 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
231a0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
231b0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
231c0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
231d0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
231e0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
231f0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
23200 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
23210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23220 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
23230 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
23240 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
23250 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
23260 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
23270 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
23280 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
23290 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
232a0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
232b0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
232c0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
232d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
232e0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
232f0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
23300 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
23310 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
23320 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
23330 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
23340 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
23350 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
23360 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65  .23.1, it was re
23370 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20  quired.** after 
23380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
23390 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
233a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
233b0 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a  ITE_ROW] that.**
233c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
233d0 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  )] be called bef
233e0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
233f0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
23400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
23410 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
23420 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
23430 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73  reset()] in this
23440 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65   way would.** re
23450 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
23460 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
23470 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73  n from sqlite3_s
23480 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
23490 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36  r.** version 3.6
234a0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
234b0 74 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c  tep() began call
234c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
234d0 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61  et()] .** automa
234e0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
234f0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
23500 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69  her than returni
23510 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
23520 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  E].  .**.** <b>G
23530 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
23540 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
23550 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
23560 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
23570 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
23580 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
23590 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
235a0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
235b0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
235c0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
235d0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
235e0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
235f0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
23600 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
23610 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
23620 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23630 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
23640 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
23650 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
23660 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
23670 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
23680 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
23690 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
236a0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
236b0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
236c0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
236d0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
236e0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
236f0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
23700 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
23710 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
23720 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
23730 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
23740 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23750 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
23760 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
23770 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
23780 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
23790 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
237a0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
237b0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
237c0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
237d0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
237e0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
237f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
23800 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
23810 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
23820 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
23830 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
23840 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
23850 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23860 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
23870 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
23880 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
23890 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
238a0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
238b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
238c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
238d0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
238e0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
238f0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
23900 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
23910 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
23920 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
23930 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
23940 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
23950 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
23960 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
23970 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
23980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
23990 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
239a0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
239b0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
239c0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
239d0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
239e0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
239f0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
23a00 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
23a10 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  ointer..**.** Se
23a20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
23a30 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
23a40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23a50 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
23a60 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
23a70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23a80 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
23a90 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
23aa0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
23ab0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
23ac0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
23ad0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
23ae0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
23af0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
23b00 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
23b10 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
23b20 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
23b30 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
23b40 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
23b50 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
23b60 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
23b70 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
23b80 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
23b90 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
23ba0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
23bb0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
23bc0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
23bd0 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
23be0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
23bf0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
23c00 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
23c10 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
23c20 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
23c30 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
23c40 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
23c50 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
23c60 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
23c70 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
23c80 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
23c90 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
23ca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23cb0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
23cc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
23cd0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
23ce0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
23cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23d00 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
23d10 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
23d20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
23d30 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
23d40 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
23d50 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
23d60 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
23d70 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
23d80 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
23d90 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
23da0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
23db0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
23dc0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
23dd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
23de0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
23df0 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
23e00 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
23e10 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
23e20 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
23e30 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
23e40 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
23e50 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
23e60 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
23e70 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
23e80 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
23e90 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
23ea0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23eb0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
23ec0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
23ed0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
23ee0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
23ef0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
23f00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23f10 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
23f20 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
23f30 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
23f40 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
23f50 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
23f60 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
23f70 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
23f80 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
23f90 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
23fa0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
23fb0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
23fc0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
23fd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23fe0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
23ff0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
24000 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
24010 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
24020 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
24030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
24040 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
24050 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
24060 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
24070 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
24080 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
24090 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
240a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
240b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
240c0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
240d0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
240e0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
240f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24100 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
24110 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
24120 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
24130 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
24140 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24150 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
24160 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
24170 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
24180 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
24190 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
241a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
241b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
241c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
241d0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
241e0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
241f0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
24200 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
24210 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
24220 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
24230 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
24240 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
24250 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24260 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
24270 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
24280 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
24290 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
242a0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
242b0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
242c0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
242d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
242e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
242f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
24300 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
24310 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
24320 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
24330 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
24340 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
24350 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
24360 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
24370 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
24380 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
24390 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
243a0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
243b0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
243c0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
243d0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
243e0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
243f0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
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 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
24420 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
24430 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
24440 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
24450 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
24460 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
24470 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
24480 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
24490 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
244a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
244b0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
244c0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
244d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
244e0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
244f0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
24500 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
24510 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
24520 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
24530 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
24540 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
24550 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
24560 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
24570 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
24580 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
24590 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
245a0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
245b0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
245c0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
245d0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
245e0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
245f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
24600 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
24610 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
24620 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
24630 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
24640 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
24650 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
24660 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
24670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24680 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
24690 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
246a0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
246b0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
246c0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
246d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
246e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
246f0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
24700 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
24710 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
24720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24730 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
24740 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
24750 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
24760 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
24770 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
24780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24790 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
247a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
247b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
247c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
247d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
247e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
247f0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
24800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24810 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
24820 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
24830 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
24840 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
24850 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
24860 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
24870 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
24880 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
24890 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
248a0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
248b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
248c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
248d0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
248e0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
248f0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
24900 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
24910 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
24920 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
24930 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
24940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24950 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
24960 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
24970 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
24980 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24990 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
249a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
249b0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
249c0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
249d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
249e0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
249f0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
24a00 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
24a10 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
24a20 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
24a30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
24a40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
24a50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
24a60 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
24a70 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
24a80 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
24a90 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
24aa0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
24ab0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
24ac0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
24ad0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
24ae0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24af0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
24b00 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
24b10 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
24b20 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
24b30 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
24b40 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
24b50 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
24b60 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
24b70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24b80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
24b90 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
24ba0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24bb0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
24bc0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
24bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
24be0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
24bf0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24c00 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
24c10 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
24c20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
24c30 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
24c40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
24c50 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
24c60 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
24c70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
24c80 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
24c90 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
24ca0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
24cb0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
24cc0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
24cd0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
24ce0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
24cf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
24d00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
24d10 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
24d20 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
24d30 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
24d40 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
24d50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24d60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24d70 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
24d80 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
24d90 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
24da0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
24db0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
24dc0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
24dd0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
24de0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
24df0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
24e00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
24e10 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
24e20 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
24e30 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
24e40 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
24e50 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
24e60 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
24e70 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
24e80 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
24e90 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
24ea0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
24eb0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
24ec0 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
24ed0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
24ee0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
24ef0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
24f00 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
24f10 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
24f20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
24f30 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
24f40 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
24f50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
24f60 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
24f70 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
24f80 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
24f90 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
24fa0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
24fb0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
24fc0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
24fd0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
24fe0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
24ff0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
25000 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
25010 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
25020 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
25030 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
25040 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
25050 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
25060 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
25070 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
25080 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
25090 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
250a0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
250b0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
250c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
250d0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
250e0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
250f0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
25100 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
25110 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
25120 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
25130 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
25140 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
25150 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
25160 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
25170 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
25180 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
25190 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
251a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
251b0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
251c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
251d0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
251e0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
251f0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
25200 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
25210 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
25220 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
25230 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
25240 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
25250 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
25260 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
25270 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
25280 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
25290 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
252a0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
252b0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
252c0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
252d0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
252e0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
252f0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
25300 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
25310 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
25320 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
25330 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
25340 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
25350 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
25360 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
25370 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
25380 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
25390 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
253a0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
253b0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
253c0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
253d0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
253e0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
253f0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
25400 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
25410 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
25420 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
25430 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
25440 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
25450 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
25460 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
25470 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
25480 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
25490 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
254a0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
254b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
254c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
254d0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
254e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
254f0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
25500 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
25510 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
25520 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
25530 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
25540 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
25550 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
25560 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
25570 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
25580 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
25590 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
255a0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
255b0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
255c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
255d0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
255e0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
255f0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
25600 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
25610 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
25620 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
25630 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
25640 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
25650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25660 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
25670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25680 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
25690 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
256a0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
256b0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
256c0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
256d0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
256e0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
256f0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
25700 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
25710 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
25720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
25730 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
25740 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
25750 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
25760 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
25770 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
25780 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
25790 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
257a0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
257b0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
257c0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
257d0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
257e0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
257f0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
25800 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
25810 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
25820 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
25830 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
25840 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
25850 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
25860 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
25870 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
25880 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
25890 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
258a0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
258b0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
258c0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
258d0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
258e0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
258f0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
25900 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
25910 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
25920 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
25930 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
25940 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
25950 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
25960 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
25970 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
25980 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
25990 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
259a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
259b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
259c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
259d0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
259e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
259f0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
25a00 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
25a10 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
25a20 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
25a30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
25a40 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
25a50 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
25a60 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
25a70 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
25a80 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
25a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25aa0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
25ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
25ac0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
25ad0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
25ae0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
25af0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
25b00 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
25b10 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
25b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25b30 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
25b40 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
25b50 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
25b60 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
25b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25b80 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
25b90 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
25ba0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
25bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25bc0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
25bd0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
25be0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
25bf0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
25c00 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
25c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25c20 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
25c30 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
25c40 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
25c50 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
25c60 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
25c70 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
25c80 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
25c90 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
25ca0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25cb0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
25cc0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
25cd0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
25ce0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
25cf0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
25d00 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
25d10 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
25d20 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
25d30 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
25d40 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
25d50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25d60 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
25d70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
25d80 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
25d90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
25da0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
25db0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
25dc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
25dd0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
25de0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
25df0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
25e00 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
25e10 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
25e20 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
25e30 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
25e40 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
25e50 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
25e60 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
25e70 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
25e80 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
25e90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
25ea0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
25eb0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
25ec0 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
25ed0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25ee0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
25ef0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25f00 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
25f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25f30 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
25f40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25f50 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
25f60 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25f70 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
25f80 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
25f90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
25fa0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
25fb0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
25fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25fd0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
25fe0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
25ff0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
26000 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26010 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
26020 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
26030 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
26040 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26050 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
26060 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
26070 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
26080 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
26090 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
260a0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
260b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
260c0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
260d0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
260e0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
260f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
26100 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
26110 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
26120 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
26130 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
26140 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
26150 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
26160 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
26170 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
26180 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
26190 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
261a0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
261b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
261c0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
261d0 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66  rors or.** or if
261e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
261f0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
26200 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
26210 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
26220 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
26230 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
26240 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
26250 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
26260 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
26270 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
26280 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
26290 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
262a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
262b0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
262c0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
262d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
262e0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
262f0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
26300 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
26310 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
26320 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
26330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
26340 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
26350 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
26360 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
26370 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
26380 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
26390 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
263a0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
263b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
263c0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
263d0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
263e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
263f0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
26400 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
26410 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
26420 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
26430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
26440 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
26450 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
26460 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
26470 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
26480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26490 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
264a0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
264b0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
264c0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
264d0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
264e0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
264f0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
26500 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
26510 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
26520 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
26530 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
26540 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
26550 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
26560 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
26570 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
26580 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
26590 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
265a0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
265b0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
265c0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
265d0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
265e0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
265f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26600 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
26610 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
26620 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
26630 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
26640 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
26650 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
26660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26670 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
26680 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
26690 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
266a0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
266b0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
266c0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
266d0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
266e0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
266f0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
26700 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
26710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26720 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
26730 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
26740 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
26750 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
26760 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
26770 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
26780 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
26790 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
267a0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
267b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
267c0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
267d0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
267e0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
267f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
26800 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26810 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
26820 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
26830 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
26840 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
26850 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
26860 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
26870 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
26880 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
26890 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
268a0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
268b0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
268c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
268d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
268e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
268f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
26900 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
26910 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26920 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
26930 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
26940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
26950 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
26960 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
26970 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
26980 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
26990 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
269a0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
269b0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
269c0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
269d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
269e0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
269f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26a00 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
26a10 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
26a20 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
26a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26a40 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
26a50 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
26a60 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26a70 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
26a80 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
26a90 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
26aa0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26ab0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
26ac0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
26ad0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26ae0 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
26af0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
26b00 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
26b10 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
26b20 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
26b30 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
26b40 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
26b50 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
26b60 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
26b70 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
26b80 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
26b90 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
26ba0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
26bb0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
26bc0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
26bd0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
26be0 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
26bf0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
26c00 6f 72 0a 2a 2a 20 74 68 65 20 74 68 65 20 73 65  or.** the the se
26c10 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
26c20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26c30 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
26c40 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
26c50 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
26c60 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
26c70 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
26c80 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
26c90 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
26ca0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
26cb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26cc0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
26cd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
26ce0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
26cf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
26d00 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
26d10 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
26d20 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
26d30 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
26d40 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
26d50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26d60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
26d70 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
26d80 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
26d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
26da0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
26db0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
26dc0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
26dd0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
26de0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
26df0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
26e00 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
26e10 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
26e20 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
26e30 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
26e40 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
26e50 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
26e60 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
26e70 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
26e80 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
26e90 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
26ea0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
26eb0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
26ec0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
26ed0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
26ee0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
26ef0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
26f00 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
26f10 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
26f20 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
26f30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
26f40 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
26f50 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
26f60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
26f70 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
26f80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
26f90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
26fa0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
26fb0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
26fc0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
26fd0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
26fe0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
26ff0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
27000 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
27010 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
27020 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
27030 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
27040 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
27050 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
27060 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
27070 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
27080 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
27090 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
270a0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
270b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
270c0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
270d0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
270e0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
270f0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
27100 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
27110 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
27120 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
27130 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
27140 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
27150 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
27160 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
27170 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
27180 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
27190 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
271a0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
271b0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
271c0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
271d0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
271e0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
271f0 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
27200 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
27210 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27220 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
27230 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27240 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
27250 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
27260 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
27270 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
27280 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
27290 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
272a0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
272b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
272c0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
272d0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
272e0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
272f0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
27300 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
27310 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
27320 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
27330 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
27340 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
27350 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
27360 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
27370 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
27380 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
27390 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
273a0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
273b0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
273c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
273d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
273e0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
273f0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
27400 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
27410 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
27420 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
27430 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
27440 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
27450 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
27460 5e 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69  ^The seventh, ei
27470 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
27480 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
27490 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
274a0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
274b0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
274c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
274d0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
274e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
274f0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
27500 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
27510 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
27520 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
27530 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
27540 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
27550 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
27560 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
27570 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
27580 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
27590 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
275a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
275b0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
275c0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
275d0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
275e0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
275f0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
27600 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
27610 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
27620 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
27630 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
27640 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 65 72 73  ass NULL poiners
27650 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
27660 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
27670 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  acks..**.** ^If 
27680 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
27690 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
276a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
276b0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
276c0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
276d0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
276e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
276f0 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
27700 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
27710 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
27720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27730 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 57  on closes..** ^W
27740 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
27750 75 72 65 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  ure callback of 
27760 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
27770 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
27780 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
27790 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
277a0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
277b0 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72  y of the pointer
277c0 20 77 68 69 63 68 20 77 61 73 0a 2a 2a 20 74 68   which was.** th
277d0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
277e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
277f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
27800 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
27810 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
27820 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
27830 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
27840 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
27850 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
27860 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
27870 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
27880 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
27890 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
278a0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
278b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
278c0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
278d0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
278e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
278f0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
27900 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
27910 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
27920 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
27930 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
27940 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27950 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
27960 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
27970 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
27980 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
27990 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
279a0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
279b0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
279c0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
279d0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
279e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
279f0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
27a00 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
27a10 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
27a20 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
27a30 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
27a40 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
27a50 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
27a60 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
27a70 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
27a80 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
27a90 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
27aa0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
27ab0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
27ac0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
27ad0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
27ae0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
27af0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
27b00 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
27b10 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
27b20 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
27b30 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
27b40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27b50 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
27b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
27b70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
27b80 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
27b90 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
27ba0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
27bb0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
27bc0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
27bd0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
27be0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
27bf0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
27c00 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
27c10 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
27c20 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
27c30 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
27c40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
27c50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
27c60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
27c70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
27c80 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
27c90 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
27ca0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
27cb0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
27cc0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
27cd0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
27ce0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
27cf0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
27d00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
27d10 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
27d20 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
27d30 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
27d40 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
27d50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27d60 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
27d70 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
27d80 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
27d90 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
27da0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
27db0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
27dc0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
27dd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27de0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
27df0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
27e00 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
27e10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
27e20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
27e30 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
27e40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
27e50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
27e60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
27e70 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
27e80 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
27e90 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
27ea0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
27eb0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
27ec0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
27ed0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
27ee0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
27ef0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
27f00 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
27f10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27f20 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
27f30 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
27f40 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
27f50 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
27f60 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
27f70 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
27f80 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
27f90 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
27fa0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
27fb0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
27fc0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
27fd0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
27fe0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
27ff0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
28000 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
28010 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
28020 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
28030 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
28040 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
28050 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
28060 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
28070 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
28080 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
28090 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
280a0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
280b0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
280c0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
280d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
280e0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
280f0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
28100 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
28110 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28120 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
28130 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
28140 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
28150 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
28160 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
28170 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
28180 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
28190 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
281a0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
281b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
281c0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
281d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
281e0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
281f0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
28200 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
28210 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
28220 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
28230 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
28240 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
28250 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
28260 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
28270 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
28280 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
28290 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
282a0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
282b0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
282c0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
282d0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
282e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
282f0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
28300 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
28310 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
28320 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
28330 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
28340 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
28350 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
28360 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
28370 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
28380 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
28390 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
283a0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
283b0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
283c0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
283d0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
283e0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
283f0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
28400 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
28410 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
28420 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
28430 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
28440 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
28450 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
28460 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
28470 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
28480 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
28490 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
284a0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
284b0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
284c0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
284d0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
284e0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
284f0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
28500 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
28510 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
28520 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
28530 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
28540 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
28550 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
28560 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
28570 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
28580 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
28590 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
285a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
285b0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
285c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
285d0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
285e0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
285f0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
28600 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
28610 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
28620 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
28630 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
28640 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
28650 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
28660 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
28670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28680 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
28690 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
286a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
286b0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
286c0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
286d0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
286e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
286f0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
28700 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
28710 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
28720 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
28730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
28740 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
28750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
28770 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
28780 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
28790 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
287a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
287b0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
287c0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
287d0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
287e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
287f0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
28800 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
28810 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
28820 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
28830 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
28840 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
28850 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
28860 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28870 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
28880 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
28890 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
288a0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
288b0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
288c0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
288d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
288e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
288f0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
28900 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
28910 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
28920 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
28930 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
28940 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
28950 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28960 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
28970 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
28980 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
28990 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
289a0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
289b0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
289c0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
289d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
289e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
289f0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
28a00 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
28a10 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
28a20 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
28a30 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
28a40 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
28a50 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
28a60 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
28a70 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
28a80 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
28a90 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
28aa0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
28ab0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
28ac0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
28ad0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
28ae0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
28af0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
28b00 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
28b10 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
28b20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
28b30 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
28b40 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
28b50 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
28b60 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
28b70 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
28b80 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
28b90 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
28ba0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
28bb0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
28bc0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
28bd0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
28be0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
28bf0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
28c00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
28c10 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
28c20 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
28c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
28c40 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
28c50 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
28c60 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
28c70 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
28c80 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
28c90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
28ca0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
28cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28cc0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
28cd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28ce0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
28cf0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
28d00 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
28d10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
28d20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
28d30 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
28d40 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
28d50 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
28d60 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
28d70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
28d80 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
28d90 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28da0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
28db0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
28dc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
28dd0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
28de0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
28df0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
28e00 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
28e10 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
28e20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
28e30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28e40 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
28e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
28e60 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
28e70 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
28e80 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
28e90 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
28ea0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
28eb0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28ec0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
28ed0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
28ee0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28ef0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
28f00 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
28f10 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28f30 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
28f40 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
28f50 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
28f60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
28f70 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
28f80 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
28f90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
28fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28fb0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
28fc0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
28fd0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
28fe0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
28ff0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
29000 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
29010 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
29020 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
29030 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
29040 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
29050 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
29060 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29070 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
29080 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
29090 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
290a0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
290b0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
290c0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
290d0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
290e0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
290f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
29100 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
29110 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
29120 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
29130 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
29140 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
29150 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
29160 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
29170 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
29180 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
29190 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
291a0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
291b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
291c0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
291d0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
291e0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
291f0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
29200 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
29210 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
29220 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
29230 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
29240 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
29250 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
29260 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
29270 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
29280 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
29290 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
292a0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
292b0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
292c0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
292d0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
292e0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
292f0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
29300 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29310 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
29320 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
29330 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
29340 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
29350 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
29360 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
29370 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
29380 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
29390 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
293a0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
293b0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
293c0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
293d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
293e0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
293f0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
29400 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
29410 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
29420 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29430 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
29440 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
29450 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
29460 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
29470 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
29480 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
29490 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
294a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
294b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
294c0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
294d0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
294e0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
294f0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
29500 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
29510 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
29520 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
29530 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
29540 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
29550 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
29560 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29570 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
29580 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
29590 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
295a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
295b0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
295c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
295d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
295e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
295f0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
29600 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
29610 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
29620 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
29630 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
29640 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
29650 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
29660 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
29670 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
29680 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
29690 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
296a0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
296b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
296c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
296d0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
296e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
296f0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
29700 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
29710 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
29720 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
29730 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
29740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29750 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
29760 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29770 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
29780 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
29790 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
297a0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
297b0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
297c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
297d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
297e0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
297f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29800 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
29810 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
29820 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
29830 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
29840 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
29850 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
29860 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
29870 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
29880 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
29890 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
298a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
298b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
298c0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
298d0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
298e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
298f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29900 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
29910 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
29920 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
29930 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
29940 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
29950 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
29960 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
29970 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
29980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29990 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
299a0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
299b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
299c0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
299d0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
299e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
299f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
29a00 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
29a10 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
29a20 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
29a30 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
29a40 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
29a50 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
29a60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
29a70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29a80 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
29a90 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
29aa0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
29ab0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
29ac0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
29ad0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
29ae0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
29af0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
29b00 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
29b10 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
29b20 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
29b30 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
29b40 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
29b50 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
29b60 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
29b70 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
29b80 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
29b90 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
29ba0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
29bb0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
29bc0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
29bd0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
29be0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
29bf0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
29c00 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
29c10 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
29c20 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
29c30 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
29c40 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
29c50 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
29c60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
29c70 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
29c80 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
29c90 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
29ca0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
29cb0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
29cc0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
29cd0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
29ce0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
29cf0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
29d00 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
29d10 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
29d20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
29d30 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
29d40 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
29d50 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
29d60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
29d70 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
29d80 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
29d90 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
29da0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
29db0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
29dc0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
29dd0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
29de0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
29df0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
29e00 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
29e10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29e20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
29e30 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
29e40 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
29e50 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
29e60 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
29e70 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
29e80 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
29e90 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
29ea0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
29eb0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
29ec0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
29ed0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
29ee0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
29ef0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
29f00 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
29f10 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
29f20 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
29f30 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
29f40 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
29f50 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
29f60 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
29f70 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
29f80 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
29f90 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
29fa0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29fb0 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
29fc0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
29fd0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
29fe0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
29ff0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2a000 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2a010 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
2a020 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
2a030 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2a040 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2a050 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2a060 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2a070 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2a080 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a090 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2a0a0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2a0b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2a0c0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2a0d0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2a0e0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2a0f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2a100 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2a110 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2a120 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2a130 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2a140 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2a150 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2a160 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2a170 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2a180 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
2a190 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
2a1a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
2a1b0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
2a1c0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
2a1d0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
2a1e0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
2a1f0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
2a200 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2a210 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2a220 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2a230 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2a240 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2a250 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2a260 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2a270 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2a280 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
2a290 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
2a2a0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2a2b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2a2c0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2a2d0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
2a2e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2a2f0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2a300 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2a310 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2a320 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
2a330 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2a340 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2a350 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
2a360 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
2a370 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
2a380 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
2a390 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
2a3a0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
2a3b0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
2a3c0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
2a3d0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
2a3e0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2a3f0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2a400 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2a410 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2a420 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2a430 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2a440 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
2a450 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2a460 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2a470 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2a480 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2a490 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2a4a0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2a4b0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2a4c0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2a4d0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
2a4e0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
2a4f0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2a500 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2a510 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2a520 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2a530 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2a540 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2a550 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2a560 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2a570 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2a580 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2a590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2a5a0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2a5b0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2a5c0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2a5d0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2a5e0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2a5f0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2a600 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2a610 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2a620 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2a630 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2a640 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2a650 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2a660 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2a670 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2a680 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2a690 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2a6a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2a6b0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2a6c0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2a6d0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
2a6e0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2a6f0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
2a700 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2a710 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
2a720 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
2a730 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2a740 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
2a750 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a760 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2a770 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a780 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
2a790 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2a7a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2a7b0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
2a7c0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
2a7d0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
2a7e0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
2a7f0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
2a800 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
2a810 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
2a820 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
2a830 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
2a840 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
2a850 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
2a860 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2a870 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2a880 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
2a890 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a8a0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
2a8b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2a8c0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2a8d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a8e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2a8f0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
2a900 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
2a910 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
2a920 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2a930 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
2a940 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
2a950 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
2a960 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
2a970 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a980 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2a990 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
2a9a0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
2a9b0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2a9c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2a9d0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
2a9e0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
2a9f0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
2aa00 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
2aa10 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
2aa20 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2aa30 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
2aa40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2aa50 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2aa60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2aa70 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2aa80 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2aa90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2aaa0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
2aab0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2aac0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
2aad0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
2aae0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2aaf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ab00 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2ab10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2ab20 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
2ab30 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
2ab40 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
2ab50 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
2ab60 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
2ab70 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2ab80 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2ab90 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2aba0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2abb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2abc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2abd0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2abe0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2abf0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2ac00 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
2ac10 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
2ac20 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
2ac30 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2ac40 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
2ac50 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
2ac60 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
2ac70 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2ac80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ac90 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
2aca0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
2acb0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
2acc0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2acd0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2ace0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2acf0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2ad00 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2ad10 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2ad20 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2ad30 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2ad40 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2ad50 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2ad60 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2ad70 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2ad80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2ad90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ada0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
2adb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2adc0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
2add0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2ade0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
2adf0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
2ae00 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
2ae10 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2ae20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
2ae30 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
2ae40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ae50 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2ae60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2ae70 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
2ae80 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
2ae90 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
2aea0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
2aeb0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
2aec0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
2aed0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
2aee0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
2aef0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
2af00 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
2af10 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
2af20 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
2af30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2af40 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
2af50 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
2af60 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
2af70 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
2af80 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
2af90 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
2afa0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
2afb0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
2afc0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
2afd0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
2afe0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2aff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b000 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2b010 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b020 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2b030 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2b040 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2b050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2b060 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
2b070 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2b080 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2b090 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2b0a0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
2b0b0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
2b0c0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
2b0d0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
2b0e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b0f0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
2b100 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
2b110 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
2b120 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
2b130 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
2b140 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
2b150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b160 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2b170 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2b180 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2b190 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2b1a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b1b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2b1c0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2b1d0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2b1e0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2b1f0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
2b200 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2b210 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
2b220 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2b230 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2b240 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b250 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b260 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2b270 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2b280 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2b290 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2b2a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2b2b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b2c0 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
2b2d0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2b2e0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2b2f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b300 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b310 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2b320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2b330 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2b340 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2b350 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
2b360 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2b370 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
2b380 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
2b390 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
2b3a0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
2b3b0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
2b3c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b3d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
2b3e0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
2b3f0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
2b400 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
2b410 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2b420 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
2b430 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
2b440 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
2b450 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
2b460 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
2b470 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
2b480 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
2b490 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
2b4a0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
2b4b0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
2b4c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2b4d0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2b4e0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2b4f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2b500 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b510 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2b520 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2b530 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
2b540 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
2b550 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b560 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
2b570 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2b580 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2b590 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2b5a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2b5b0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2b5c0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
2b5d0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
2b5e0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
2b5f0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
2b600 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
2b610 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2b620 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
2b630 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
2b640 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b650 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
2b660 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2b670 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2b680 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2b690 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2b6a0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2b6b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2b6c0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2b6d0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2b6e0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2b6f0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2b700 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2b710 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
2b720 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2b730 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2b740 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2b750 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2b760 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2b770 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b780 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2b790 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
2b7a0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2b7b0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2b7c0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2b7d0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
2b7e0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
2b7f0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
2b800 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
2b810 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
2b820 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
2b830 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
2b840 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
2b850 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
2b860 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
2b870 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
2b880 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
2b890 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2b8a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2b8b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2b8c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b8d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2b8e0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2b8f0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2b900 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2b910 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2b920 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2b930 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2b940 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2b950 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2b960 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2b970 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2b980 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2b990 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2b9a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b9b0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2b9c0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2b9d0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2b9e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b9f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2ba00 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2ba10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ba20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ba30 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2ba40 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2ba50 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2ba60 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2ba70 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
2ba80 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
2ba90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2baa0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
2bab0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
2bac0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
2bad0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
2bae0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
2baf0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
2bb00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2bb10 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
2bb20 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
2bb30 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2bb40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2bb50 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
2bb60 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
2bb70 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2bb80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2bb90 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
2bba0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
2bbb0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
2bbc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
2bbd0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
2bbe0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
2bbf0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
2bc00 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2bc10 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
2bc20 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2bc30 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
2bc40 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2bc50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2bc60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
2bc70 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
2bc80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2bc90 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
2bca0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2bcb0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
2bcc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bcd0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2bce0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2bcf0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2bd00 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2bd10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2bd20 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
2bd30 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
2bd40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2bd50 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
2bd60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2bd70 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
2bd80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2bd90 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
2bda0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2bdb0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
2bdc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2bdd0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2bde0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2bdf0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2be00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2be10 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2be20 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2be30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2be40 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
2be50 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2be60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2be70 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
2be80 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2be90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2bea0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
2beb0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2bec0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
2bed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2bee0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
2bef0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2bf00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
2bf10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2bf20 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2bf30 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2bf40 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2bf50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
2bf60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2bf70 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2bf80 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2bf90 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2bfa0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2bfb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2bfc0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2bfd0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2bfe0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2bff0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2c000 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2c010 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2c020 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2c030 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2c040 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2c050 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c060 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
2c070 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2c080 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2c090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c0a0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2c0b0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
2c0c0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
2c0d0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
2c0e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2c0f0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
2c100 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
2c110 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
2c120 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
2c130 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c140 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
2c150 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2c160 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
2c170 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
2c180 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
2c190 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2c1a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2c1b0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2c1c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2c1d0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2c1e0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2c1f0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
2c200 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
2c210 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c220 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
2c230 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
2c240 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
2c250 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
2c260 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
2c270 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
2c280 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
2c290 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
2c2a0 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
2c2b0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
2c2c0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
2c2d0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
2c2e0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
2c2f0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
2c300 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
2c310 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
2c320 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
2c330 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
2c340 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
2c350 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2c360 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
2c370 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
2c380 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
2c390 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
2c3a0 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
2c3b0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
2c3c0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
2c3d0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
2c3e0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
2c3f0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
2c400 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
2c410 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
2c420 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
2c430 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
2c440 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
2c450 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
2c460 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
2c470 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2c480 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
2c490 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
2c4a0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
2c4b0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
2c4c0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
2c4d0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
2c4e0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
2c4f0 73 20 61 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  s a application 
2c500 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
2c510 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
2c520 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
2c530 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2c540 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
2c550 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
2c560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2c570 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
2c580 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
2c590 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
2c5a0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
2c5b0 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
2c5c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
2c5d0 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
2c5e0 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
2c5f0 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
2c600 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
2c610 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
2c620 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
2c630 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
2c640 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2c650 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2c660 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
2c670 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
2c680 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
2c690 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
2c6a0 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
2c6b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
2c6c0 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
2c6d0 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
2c6e0 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
2c6f0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
2c700 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
2c710 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
2c720 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
2c730 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
2c740 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2c750 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
2c760 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
2c770 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
2c780 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
2c790 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
2c7a0 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
2c7b0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
2c7c0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
2c7d0 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
2c7e0 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
2c7f0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2c800 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
2c810 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
2c820 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
2c830 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
2c840 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
2c850 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
2c860 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
2c870 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
2c880 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
2c890 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
2c8a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2c8b0 6d 75 73 74 20 61 6c 77 61 79 20 72 65 74 75 72  must alway retur
2c8c0 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
2c8d0 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
2c8e0 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
2c8f0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
2c900 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
2c910 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
2c920 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
2c930 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
2c940 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
2c950 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
2c960 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
2c970 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
2c980 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
2c990 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
2c9a0 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
2c9b0 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
2c9c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
2c9d0 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
2c9e0 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
2c9f0 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
2ca00 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
2ca10 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
2ca20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
2ca30 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
2ca40 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
2ca50 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
2ca60 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
2ca70 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
2ca80 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
2ca90 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
2caa0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
2cab0 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
2cac0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
2cad0 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
2cae0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2caf0 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
2cb00 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
2cb10 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
2cb20 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2cb30 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
2cb40 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2cb50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cb60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2cb70 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2cb80 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2cb90 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2cba0 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
2cbb0 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
2cbc0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
2cbd0 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
2cbe0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
2cbf0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2cc00 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
2cc10 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
2cc20 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
2cc30 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
2cc40 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
2cc50 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
2cc60 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
2cc70 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
2cc80 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
2cc90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cca0 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
2ccb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2ccc0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  se()]..**.** See
2ccd0 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
2cce0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2ccf0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
2cd00 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2cd10 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
2cd20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2cd30 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
2cd40 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2cd50 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2cd60 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2cd70 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
2cd80 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2cd90 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2cda0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2cdb0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2cdc0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2cdd0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2cde0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2cdf0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2ce00 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2ce10 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
2ce20 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2ce30 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2ce40 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2ce50 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2ce60 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2ce70 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2ce80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2ce90 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2cea0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
2ceb0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2cec0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
2ced0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2cee0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2cef0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2cf00 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2cf10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2cf20 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2cf30 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
2cf40 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
2cf50 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
2cf60 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2cf70 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
2cf80 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
2cf90 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
2cfa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
2cfb0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
2cfc0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
2cfd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cfe0 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
2cff0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2d000 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2d010 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2d020 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2d030 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2d040 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2d050 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2d060 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2d070 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2d080 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2d090 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2d0a0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2d0b0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2d0c0 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2d0d0 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2d0e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2d0f0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2d100 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2d110 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2d120 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2d130 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2d140 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2d150 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2d160 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
2d170 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
2d180 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
2d190 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
2d1a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2d1b0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2d1c0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2d1d0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2d1e0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2d1f0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2d200 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2d210 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2d220 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2d230 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2d240 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2d250 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2d260 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
2d270 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2d280 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2d290 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2d2a0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
2d2b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2d2c0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2d2d0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
2d2e0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2d2f0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2d300 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2d310 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
2d320 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2d330 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2d340 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2d350 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
2d360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2d370 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2d380 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2d390 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2d3a0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2d3b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2d3c0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2d3d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2d3e0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2d3f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d400 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2d410 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d420 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2d430 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2d440 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2d450 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2d460 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2d470 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2d480 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2d490 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2d4a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2d4b0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2d4c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2d4d0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2d4e0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
2d4f0 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
2d500 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
2d510 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2d520 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2d530 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2d540 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2d550 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2d560 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2d570 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2d580 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2d590 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2d5a0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2d5b0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2d5c0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2d5d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2d5e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2d5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d600 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2d610 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2d620 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2d630 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2d640 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2d650 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2d660 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2d670 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2d680 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2d690 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2d6a0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2d6b0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2d6c0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2d6d0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2d6e0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2d6f0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2d700 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2d710 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2d720 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2d730 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2d740 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2d750 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2d760 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2d770 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2d780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2d790 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2d7a0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2d7b0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2d7c0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2d7d0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2d7e0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2d7f0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2d800 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
2d810 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2d820 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2d830 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
2d840 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2d850 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2d860 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
2d870 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2d880 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
2d890 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
2d8a0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
2d8b0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
2d8c0 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
2d8d0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2d8e0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
2d8f0 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
2d900 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2d910 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2d920 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
2d930 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2d940 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2d950 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
2d960 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
2d970 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2d980 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2d990 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2d9a0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2d9b0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
2d9c0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2d9d0 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
2d9e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
2d9f0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
2da00 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
2da10 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
2da20 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
2da30 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
2da40 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2da50 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
2da60 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
2da70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
2da80 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2da90 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2daa0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2dab0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2dac0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2dad0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2dae0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2daf0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2db00 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2db10 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
2db20 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
2db30 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
2db40 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
2db50 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2db60 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
2db70 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
2db80 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
2db90 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
2dba0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
2dbb0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
2dbc0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2dbd0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
2dbe0 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
2dbf0 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
2dc00 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
2dc10 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
2dc20 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
2dc30 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
2dc40 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
2dc50 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2dc60 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
2dc70 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
2dc80 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
2dc90 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
2dca0 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
2dcb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
2dcc0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
2dcd0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2dce0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2dcf0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2dd00 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
2dd10 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2dd20 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2dd30 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2dd40 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2dd50 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2dd60 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
2dd70 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
2dd80 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
2dd90 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
2dda0 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
2ddb0 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
2ddc0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
2ddd0 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
2dde0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
2ddf0 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
2de00 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
2de10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
2de20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
2de30 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
2de40 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2de50 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
2de60 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2de70 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2de80 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2de90 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2dea0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
2deb0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
2dec0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
2ded0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
2dee0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
2def0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
2df00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2df10 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
2df20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
2df30 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
2df40 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
2df50 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
2df60 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2df70 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
2df80 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
2df90 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
2dfa0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
2dfb0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
2dfc0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
2dfd0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2dfe0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
2dff0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
2e000 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
2e010 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
2e020 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
2e030 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2e040 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
2e050 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
2e060 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
2e070 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2e080 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2e090 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
2e0a0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2e0b0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2e0c0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2e0d0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2e0e0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2e0f0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2e100 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2e110 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2e120 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2e130 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2e140 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2e150 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2e160 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2e170 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2e180 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2e190 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2e1a0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2e1b0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2e1c0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2e1d0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2e1e0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2e1f0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2e200 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2e210 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2e220 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2e230 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2e240 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2e250 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2e260 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2e270 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2e280 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2e290 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2e2a0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2e2b0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
2e2c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
2e2d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
2e2e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e2f0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2e300 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e310 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
2e320 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
2e330 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
2e340 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
2e350 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
2e360 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
2e370 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
2e380 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2e390 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2e3a0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2e3b0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2e3c0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2e3d0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
2e3e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2e3f0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
2e400 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
2e410 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
2e420 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
2e430 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
2e440 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
2e450 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
2e460 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
2e470 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
2e480 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2e490 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2e4a0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
2e4b0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
2e4c0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
2e4d0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
2e4e0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
2e4f0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
2e500 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
2e510 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2e520 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
2e530 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
2e540 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2e550 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2e560 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2e570 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
2e580 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
2e590 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
2e5a0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
2e5b0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
2e5c0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
2e5d0 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
2e5e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2e5f0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
2e600 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
2e610 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
2e620 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
2e630 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2e640 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2e650 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2e660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e670 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
2e680 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
2e690 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e6a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e6b0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
2e6c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e6d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2e6e0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2e6f0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
2e700 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e710 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
2e720 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2e730 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
2e740 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2e750 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
2e760 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2e770 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
2e780 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
2e790 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2e7a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2e7b0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
2e7c0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
2e7d0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
2e7e0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
2e7f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
2e800 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
2e810 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2e820 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2e830 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2e840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2e850 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2e860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2e870 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2e880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
2e8a0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
2e8b0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
2e8c0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
2e8d0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2e8e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e8f0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
2e900 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2e910 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2e920 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2e930 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2e940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e950 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2e960 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2e970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2e980 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
2e990 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2e9a0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2e9b0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2e9c0 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2e9d0 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2e9e0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2e9f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2ea00 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2ea10 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2ea20 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2ea30 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2ea40 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2ea50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2ea60 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2ea70 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2ea80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
2ea90 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
2eaa0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
2eab0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
2eac0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ead0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2eae0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
2eaf0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
2eb00 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
2eb10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eb20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2eb30 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2eb40 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2eb50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2eb60 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2eb70 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2eb80 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
2eb90 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
2eba0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2ebb0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2ebc0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2ebd0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2ebe0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2ebf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2ec00 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
2ec10 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
2ec20 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
2ec30 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2ec40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2ec50 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2ec60 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2ec70 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
2ec80 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
2ec90 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
2eca0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2ecb0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2ecc0 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
2ecd0 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
2ece0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2ecf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2ed00 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2ed10 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
2ed20 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2ed30 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
2ed40 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
2ed50 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2ed60 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2ed70 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
2ed80 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
2ed90 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
2eda0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
2edb0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
2edc0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2edd0 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
2ede0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
2edf0 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
2ee00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
2ee10 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
2ee20 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
2ee30 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
2ee40 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2ee50 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2ee60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ee70 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
2ee80 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
2ee90 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
2eea0 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
2eeb0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
2eec0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2eed0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2eee0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2eef0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2ef00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2ef10 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2ef20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
2ef30 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2ef40 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2ef50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2ef60 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2ef70 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2ef80 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2ef90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2efa0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2efb0 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
2efc0 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
2efd0 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
2efe0 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
2eff0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2f000 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2f010 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2f020 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2f030 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
2f040 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
2f050 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
2f060 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
2f070 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
2f080 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
2f090 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
2f0a0 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
2f0b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
2f0c0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
2f0d0 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
2f0e0 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
2f0f0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
2f100 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
2f110 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
2f120 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
2f130 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2f140 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2f150 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2f160 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2f170 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2f180 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
2f190 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
2f1a0 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
2f1b0 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
2f1c0 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
2f1d0 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
2f1e0 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
2f1f0 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
2f200 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
2f210 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2f220 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
2f230 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
2f240 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2f250 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
2f260 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
2f270 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
2f280 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
2f290 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
2f2a0 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
2f2b0 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
2f2c0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
2f2d0 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
2f2e0 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
2f2f0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2f300 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2f310 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2f320 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
2f330 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2f340 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
2f350 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f360 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
2f370 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2f380 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2f390 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2f3a0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2f3b0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2f3c0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2f3d0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2f3e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2f3f0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2f400 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2f410 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2f420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f430 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2f440 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2f450 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2f460 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2f470 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2f480 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2f490 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
2f4a0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2f4b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
2f4c0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
2f4d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2f4e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2f4f0 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
2f500 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2f510 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2f520 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2f530 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2f540 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2f550 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2f560 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2f570 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2f580 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2f590 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2f5a0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2f5b0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
2f5c0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
2f5d0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
2f5e0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2f5f0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
2f600 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2f610 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2f620 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
2f630 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2f640 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
2f650 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2f660 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
2f670 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
2f680 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2f690 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
2f6a0 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
2f6b0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
2f6c0 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
2f6d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
2f6e0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
2f6f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
2f700 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
2f710 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2f720 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
2f730 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
2f740 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
2f750 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2f760 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
2f770 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2f780 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
2f790 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
2f7a0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
2f7b0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
2f7c0 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
2f7d0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2f7e0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2f7f0 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2f800 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2f810 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
2f820 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
2f830 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2f840 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
2f850 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
2f860 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
2f870 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
2f880 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
2f890 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
2f8a0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2f8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2f8c0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2f8d0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2f8e0 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2f8f0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2f900 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2f910 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2f920 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2f930 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2f940 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
2f950 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
2f960 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
2f970 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
2f980 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
2f990 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
2f9a0 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
2f9b0 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
2f9c0 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
2f9d0 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
2f9e0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
2f9f0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2fa00 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
2fa10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2fa20 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2fa30 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2fa40 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2fa50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2fa60 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
2fa70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
2fa80 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2fa90 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2faa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2fab0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2fac0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2fad0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2fae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2faf0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2fb00 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
2fb10 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
2fb20 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2fb30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2fb40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fb50 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2fb60 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2fb70 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2fb80 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2fb90 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2fba0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2fbb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
2fbc0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
2fbd0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
2fbe0 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
2fbf0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2fc00 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
2fc10 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2fc20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2fc30 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
2fc40 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
2fc50 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
2fc60 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2fc70 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2fc80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2fc90 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
2fca0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
2fcb0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2fcc0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
2fcd0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2fce0 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
2fcf0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
2fd00 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
2fd10 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
2fd20 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
2fd30 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2fd40 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
2fd50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45  ager Cache.** KE
2fd60 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
2fd70 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54  cache}.**.** ^(T
2fd80 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
2fd90 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
2fda0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
2fdb0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
2fdc0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
2fdd0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
2fde0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
2fdf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
2fe00 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
2fe10 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
2fe20 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
2fe30 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
2fe40 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
2fe50 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
2fe60 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2fe70 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
2fe80 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
2fe90 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2fea0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2feb0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2fec0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2fed0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2fee0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2fef0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2ff00 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2ff10 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2ff20 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2ff30 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2ff40 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2ff50 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
2ff60 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
2ff70 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
2ff80 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
2ff90 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2ffa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2ffb0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2ffc0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
2ffd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2ffe0 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
2fff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30000 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
30010 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
30020 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
30030 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
30040 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
30050 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
30060 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
30070 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
30080 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
30090 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
300a0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
300b0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
300c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
300d0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
300e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
300f0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
30100 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
30110 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
30120 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
30130 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
30140 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
30150 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
30160 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
30170 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
30180 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
30190 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
301a0 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
301b0 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
301c0 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e].*/.int sqlite
301d0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
301e0 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
301f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
30200 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
30210 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e  p Memory.**.** ^
30220 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
30230 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
30240 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
30250 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
30260 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
30270 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
30280 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
30290 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
302a0 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
302b0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
302c0 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65  ry.   Memory use
302d0 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
302e0 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20  ase.** pages to 
302f0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
30300 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
30310 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  e of non-essenti
30320 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73  al memory..** ^s
30330 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
30340 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
30350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
30360 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
30370 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
30380 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
30390 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
303a0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
303b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
303c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
303d0 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f  outine is a no-o
303e0 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f  p returning zero
303f0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
30400 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69   not compiled wi
30410 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  th [SQLITE_ENABL
30420 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
30430 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ENT]..*/.int sql
30440 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30450 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
30460 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
30470 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
30480 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
30490 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
304a0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e  eap_limit64() in
304b0 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64  terface sets and
304c0 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a  /or queries the.
304d0 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e  ** soft limit on
304e0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
304f0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
30500 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
30510 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
30520 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
30530 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f  o keep heap memo
30540 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62  ry utilization b
30550 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65  elow the soft he
30560 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72  ap.** limit by r
30570 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62  educing the numb
30580 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64  er of pages held
30590 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
305a0 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65  he.** as heap me
305b0 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72  mory usages appr
305c0 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74  oaches the limit
305d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68  ..** ^The soft h
305e0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f  eap limit is "so
305f0 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e  ft" because even
30600 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73   though SQLite s
30610 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a  trives to stay.*
30620 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69  * below the limi
30630 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65  t, it will excee
30640 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68  d the limit rath
30650 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65  er than generate
30660 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  .** an [SQLITE_N
30670 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e  OMEM] error.  In
30680 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
30690 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
306a0 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72  t .** is advisor
306b0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
306c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
306d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66  from sqlite3_sof
306e0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
306f0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a   is the size of.
30700 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
30710 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20   limit prior to 
30720 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74  the call.  ^If t
30730 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
30740 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65   negative.** the
30750 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d  n no change is m
30760 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20  ade to the soft 
30770 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e  heap limit.  Hen
30780 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ce, the current.
30790 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  ** size of the s
307a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
307b0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
307c0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   by invoking.** 
307d0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
307e0 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68  p_limit64() with
307f0 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75   a negative argu
30800 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ment..**.** ^If 
30810 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
30820 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  s zero then the 
30830 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
30840 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
30850 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65  ** ^(The soft he
30860 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  ap limit is not 
30870 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20  enforced in the 
30880 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
30890 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65  tation.** if one
308a0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c   or more of foll
308b0 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73  owing conditions
308c0 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a   are true:.**.**
308d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
308e0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
308f0 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f  t is set to zero
30900 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79  ..** <li> Memory
30910 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64   accounting is d
30920 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
30930 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74  combination of t
30940 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  he.**      [sqli
30950 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
30960 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
30970 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74  ATUS],...) start
30980 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64  -time option and
30990 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51  .**      the [SQ
309a0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
309b0 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d  STATUS] compile-
309c0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
309d0 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74  <li> An alternat
309e0 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69  ive page cache i
309f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
30a00 20 73 70 65 63 69 66 65 64 20 75 73 69 6e 67 0a   specifed using.
30a10 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
30a20 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
30a30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c  _CONFIG_PCACHE],
30a40 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ...)..** <li> Th
30a50 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c  e page cache all
30a60 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20  ocates from its 
30a70 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20  own memory pool 
30a80 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20  supplied.**     
30a90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   by [sqlite3_con
30aa0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
30ab0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e  FIG_PAGECACHE],.
30ac0 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a  ..) rather than.
30ad0 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65  **      from the
30ae0 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29   heap..** </ul>)
30af0 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e  ^.**.** Beginnin
30b00 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
30b10 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65  rsion 3.7.3, the
30b20 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
30b30 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20   is enforced.** 
30b40 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
30b50 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
30b60 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
30b70 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
30b80 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
30b90 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76  me option is inv
30ba0 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c  oked.  With [SQL
30bb0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
30bc0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a  Y_MANAGEMENT],.*
30bd0 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
30be0 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
30bf0 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72  d on every memor
30c00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57  y allocation.  W
30c10 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54  ithout.** [SQLIT
30c20 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
30c30 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65  MANAGEMENT], the
30c40 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
30c50 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65   is only enforce
30c60 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79  d.** when memory
30c70 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   is allocated by
30c80 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e   the page cache.
30c90 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73    Testing sugges
30ca0 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a  ts that because.
30cb0 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68  ** the page cach
30cc0 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69  e is the predomi
30cd0 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72  nate memory user
30ce0 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74   in SQLite, most
30cf0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
30d00 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64   will achieve ad
30d10 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70  equate soft heap
30d20 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65   limit enforceme
30d30 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68  nt without.** th
30d40 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45  e use of [SQLITE
30d50 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
30d60 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a  ANAGEMENT]..**.*
30d70 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e  * The circumstan
30d80 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20  ces under which 
30d90 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f  SQLite will enfo
30da0 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61  rce the soft hea
30db0 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63  p limit may.** c
30dc0 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65  hanges in future
30dd0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
30de0 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ite..*/.sqlite3_
30df0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
30e00 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
30e10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
30e20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30e30 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
30e40 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
30e50 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
30e60 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
30e70 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
30e80 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
30e90 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
30ea0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
30eb0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
30ec0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
30ed0 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
30ee0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
30ef0 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
30f00 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30f10 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
30f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
30f30 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
30f40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
30f50 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
30f60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
30f70 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
30f80 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
30f90 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a  mit(int N);.../*
30fa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
30fb0 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
30fc0 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
30fd0 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
30fe0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
30ff0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
31000 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
31010 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
31020 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
31030 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
31040 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
31050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31060 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
31070 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
31080 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
31090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
310a0 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
310b0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
310c0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
310d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
310e0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
310f0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
31100 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
31110 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
31120 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
31130 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
31140 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
31150 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
31160 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
31170 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
31180 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
31190 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
311a0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
311b0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
311c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
311d0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
311e0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
311f0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
31200 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
31210 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
31220 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
31230 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
31240 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
31250 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
31260 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
31270 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
31280 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
31290 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
312a0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
312b0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
312c0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
312d0 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
312e0 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
312f0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
31300 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
31310 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
31320 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
31330 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31340 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
31350 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
31360 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
31370 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
31380 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
31390 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
313a0 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
313b0 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
313c0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
313d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
313e0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
313f0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
31400 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
31410 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
31420 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
31430 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
31440 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
31450 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
31460 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
31470 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
31480 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
31490 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
314a0 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
314b0 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
314c0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
314d0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
314e0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
314f0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
31500 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
31510 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
31520 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
31530 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
31540 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
31550 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
31560 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
31570 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
31580 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
31590 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
315a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
315b0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
315c0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
315d0 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
315e0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
315f0 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
31600 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
31610 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31620 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
31630 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
31640 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
31650 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
31660 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31670 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
31680 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
31690 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
316a0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
316b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
316c0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
316d0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
316e0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
316f0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
31700 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
31710 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
31720 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
31730 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
31740 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
31750 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
31760 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
31770 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
31780 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
31790 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
317a0 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
317b0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
317c0 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
317d0 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
317e0 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
317f0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
31800 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
31810 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
31820 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
31830 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
31840 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
31850 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
31860 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
31870 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
31880 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
31890 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
318a0 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
318b0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
318c0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
318d0 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
318e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
318f0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
31900 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
31910 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
31920 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
31930 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
31940 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
31950 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
31960 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
31970 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
31980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31990 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
319a0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
319b0 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
319c0 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
319d0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
319e0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
319f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
31a00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
31a10 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
31a20 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
31a30 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
31a40 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
31a50 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
31a60 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
31a70 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
31a80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
31a90 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
31aa0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
31ab0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
31ac0 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
31ad0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
31ae0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
31af0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
31b00 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
31b10 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
31b20 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
31b30 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
31b40 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
31b50 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
31b60 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
31b70 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
31b80 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
31b90 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
31ba0 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
31bb0 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
31bc0 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
31bd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
31be0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
31bf0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
31c00 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
31c10 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
31c20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
31c30 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
31c40 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
31c50 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
31c60 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
31c70 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
31c80 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
31c90 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
31ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31cb0 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
31cc0 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  nsion.**.** ^Thi
31cd0 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
31ce0 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
31cf0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
31d00 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
31d10 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
31d20 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
31d30 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
31d40 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
31d50 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65  d an.** SQLite e
31d60 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
31d70 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
31d80 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
31d90 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70  .** ^The entry p
31da0 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a  oint is zProc..*
31db0 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  * ^zProc may be 
31dc0 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  0, in which case
31dd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31de0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
31df0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
31e00 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
31e10 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nit"..** ^The sq
31e20 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
31e30 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
31e40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
31e50 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
31e60 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
31e70 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
31e80 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
31e90 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
31ea0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
31eb0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
31ec0 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
31ed0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
31ee0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
31ef0 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a  all attempt to.*
31f00 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  * fill *pzErrMsg
31f10 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73   with error mess
31f20 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
31f30 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
31f40 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
31f50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54  te3_malloc()]. T
31f60 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
31f70 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72  ion.** should fr
31f80 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
31f90 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
31fa0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
31fb0 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
31fc0 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
31fd0 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  bled using.** [s
31fe0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
31ff0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
32000 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
32010 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74   this API,.** ot
32020 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
32030 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
32040 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
32050 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  o the [load_exte
32060 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63  nsion() SQL func
32070 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  tion]..*/.int sq
32080 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
32090 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
320a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
320b0 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
320c0 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
320d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
320e0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
320f0 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
32100 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
32110 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
32120 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
32130 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
32140 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
32150 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
32160 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
32170 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
32180 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
32190 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
321a0 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
321b0 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
321c0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
321d0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
321e0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
321f0 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f  ** ^So as not to
32200 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
32210 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
32220 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
32230 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
32240 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
32250 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
32260 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
32270 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
32280 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
32290 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
322a0 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
322b0 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
322c0 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72  ing API.** is pr
322d0 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
322e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
322f0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
32300 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f  chanism on and o
32310 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  ff..**.** ^Exten
32320 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
32330 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
32340 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
32350 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73  ..** ^Call the s
32360 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
32370 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
32380 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
32390 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20  f==1.** to turn 
323a0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
323b0 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74  g on and call it
323c0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
323d0 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63  o turn.** it bac
323e0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
323f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
32400 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
32410 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
32420 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
32430 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f  * CAPI3REF: Auto
32440 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53  matically Load S
32450 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64  tatically Linked
32460 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a   Extensions.**.*
32470 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
32480 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e  e causes the xEn
32490 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74  tryPoint() funct
324a0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
324b0 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65  d for.** each ne
324c0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
324d0 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20  ection] that is 
324e0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64  created.  The id
324f0 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a  ea here is that.
32500 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  ** xEntryPoint()
32510 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f   is the entry po
32520 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63  int for a static
32530 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69  ally linked SQLi
32540 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20  te extension.** 
32550 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75  that is to be au
32560 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64  tomatically load
32570 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20  ed into all new 
32580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32590 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  ions..**.** ^(Ev
325a0 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75  en though the fu
325b0 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65  nction prototype
325c0 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74   shows that xEnt
325d0 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a  ryPoint() takes.
325e0 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  ** no arguments 
325f0 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64  and returns void
32600 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  , SQLite invokes
32610 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77   xEntryPoint() w
32620 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67  ith three.** arg
32630 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63  uments and expec
32640 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72  ts and integer r
32650 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20  esult as if the 
32660 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65  signature of the
32670 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  .** entry point 
32680 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  where as follows
32690 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
326a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62  ote><pre>.** &nb
326b0 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50  sp;  int xEntryP
326c0 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20  oint(.** &nbsp; 
326d0 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a     sqlite3 *db,.
326e0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
326f0 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  st char **pzErrM
32700 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  sg,.** &nbsp;   
32710 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
32720 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
32730 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e  es *pThunk.** &n
32740 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72  bsp;  );.** </pr
32750 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
32760 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78  ^.**.** If the x
32770 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69  EntryPoint routi
32780 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  ne encounters an
32790 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c   error, it shoul
327a0 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67  d make *pzErrMsg
327b0 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
327c0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
327d0 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69  r message (obtai
327e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
327f0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a  3_mprintf()]).**
32800 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61   and return an a
32810 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
32820 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74  r code].  ^SQLit
32830 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a  e ensures that *
32840 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e  pzErrMsg.** is N
32850 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  ULL before calli
32860 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69  ng the xEntryPoi
32870 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77  nt().  ^SQLite w
32880 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73  ill invoke.** [s
32890 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
328a0 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65  n *pzErrMsg afte
328b0 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  r xEntryPoint() 
328c0 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e  returns.  ^If an
328d0 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  y.** xEntryPoint
328e0 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  () returns an er
328f0 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ror, the [sqlite
32900 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
32910 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
32920 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
32930 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68  en_v2()] call th
32940 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
32950 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
32960 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ll fail..**.** ^
32970 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
32980 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58  auto_extension(X
32990 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20  ) with an entry 
329a0 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20  point X that is 
329b0 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68  already.** on th
329c0 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61  e list of automa
329d0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
329e0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
329f0 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f  op. ^No entry po
32a00 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63  int.** will be c
32a10 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20  alled more than 
32a20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61  once for each da
32a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32a40 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64  n that is opened
32a50 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
32a60 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  : [sqlite3_reset
32a70 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
32a80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
32a90 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
32aa0 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
32ab0 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
32ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
32ad0 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
32ae0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
32af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
32b00 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20  erface disables 
32b10 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78  all automatic ex
32b20 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75  tensions previou
32b30 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  sly.** registere
32b40 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
32b50 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
32b60 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  )]..*/.void sqli
32b70 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
32b80 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
32b90 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
32ba0 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
32bb0 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
32bc0 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
32bd0 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
32be0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
32bf0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
32c00 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
32c10 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
32c20 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
32c30 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
32c40 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
32c50 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
32c60 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
32c70 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
32c80 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
32c90 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
32ca0 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
32cb0 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
32cc0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
32cd0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
32ce0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
32cf0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
32d00 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
32d10 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
32d20 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
32d30 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
32d40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
32d50 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
32d60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
32d70 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
32d80 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
32d90 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
32da0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
32db0 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
32dc0 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
32dd0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
32de0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
32df0 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
32e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
32e10 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
32e20 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
32e30 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
32e40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
32e50 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule}.**.** This 
32e60 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
32e70 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20  imes called a a 
32e80 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  "virtual table m
32e90 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69  odule", .** defi
32ea0 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nes the implemen
32eb0 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72  tation of a [vir
32ec0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a  tual tables].  .
32ed0 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
32ee0 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c  e consists mostl
32ef0 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
32f00 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
32f10 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61  ** ^A virtual ta
32f20 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72  ble module is cr
32f30 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67  eated by filling
32f40 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74   in a persistent
32f50 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
32f60 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
32f70 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69  nd passing a poi
32f80 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73  nter to that ins
32f90 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tance.** to [sql
32fa0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
32fb0 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  le()] or [sqlite
32fc0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
32fd0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  v2()]..** ^The r
32fe0 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61  egistration rema
32ff0 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  ins valid until 
33000 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62  it is replaced b
33010 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  y a different.**
33020 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c   module or until
33030 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33040 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65  onnection] close
33050 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a  s.  The content.
33060 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ** of this struc
33070 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68  ture must not ch
33080 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69 73  ange while it is
33090 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
330a0 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65  .** any database
330b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a   connection..*/.
330c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
330d0 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
330e0 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
330f0 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
33100 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
33110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
33120 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
33130 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
33140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
33150 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
33160 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
33170 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
33180 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
33190 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
331a0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
331b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
331c0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
331d0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
331e0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
331f0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
33200 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
33210 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
33220 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
33230 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
33240 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
33250 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
33260 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
33270 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
33280 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
33290 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
332a0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
332b0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
332c0 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
332d0 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
332e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
332f0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
33300 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
33310 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
33320 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
33330 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
33340 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
33350 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
33360 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
33370 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
33380 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
33390 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
333a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
333b0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
333c0 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
333d0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
333e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
333f0 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
33400 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
33410 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
33420 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
33430 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
33440 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
33450 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
33460 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
33470 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
33480 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
33490 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
334a0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
334b0 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
334c0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
334d0 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
334e0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
334f0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
33500 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
33510 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
33520 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
33530 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
33540 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
33550 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
33560 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
33570 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
33580 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
33590 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
335a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
335b0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
335c0 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
335d0 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
335e0 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
335f0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
33600 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
33610 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
33620 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
33630 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
33640 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52  mation.** KEYWOR
33650 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
33660 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
33670 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
33680 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
33690 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
336a0 72 65 73 20 69 73 20 75 73 65 64 20 61 73 20 70  res is used as p
336b0 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76  art.** of the [v
336c0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e  irtual table] in
336d0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61  terface to.** pa
336e0 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ss information i
336f0 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20  nto and receive 
33700 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74  the reply from t
33710 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a  he [xBestIndex].
33720 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b  ** method of a [
33730 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33740 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c  dule].  The fiel
33750 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
33760 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
33770 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
33780 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
33790 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
337a0 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
337b0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
337c0 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
337d0 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ields..**.** ^(T
337e0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
337f0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
33800 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
33810 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66  traints of the f
33820 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  orm:.**.** <bloc
33830 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50  kquote>column OP
33840 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74   expr</blockquot
33850 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f  e>.**.** where O
33860 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
33870 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
33880 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61  t;=.)^  ^(The pa
33890 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
338a0 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
338b0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
338c0 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  op using one of 
338d0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
338e0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
338f0 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45  EQ | SQLITE_INDE
33900 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61  X_CONSTRAINT_ va
33910 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68  lues].)^.** ^(Th
33920 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
33930 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
33940 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
33950 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20  t[].iColumn.)^  
33960 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  ^(aConstraint[].
33970 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
33980 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
33990 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
339a0 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
339b0 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
339c0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
339d0 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
339e0 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
339f0 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  not.)^.**.** ^Th
33a00 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f  e optimizer auto
33a10 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74  matically invert
33a20 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66  s terms of the f
33a30 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c  orm "expr OP col
33a40 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65  umn".** and make
33a50 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69  s other simplifi
33a60 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57  cations to the W
33a70 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61  HERE clause in a
33a80 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  n attempt to.** 
33a90 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52  get as many WHER
33aa0 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
33ab0 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f  nto the form sho
33ac0 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73  wn above as poss
33ad0 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43  ible..** ^The aC
33ae0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
33af0 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
33b00 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
33b10 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65  s that are.** re
33b20 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61  levant to the pa
33b30 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
33b40 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
33b50 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66  ried..**.** ^Inf
33b60 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
33b70 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
33b80 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
33b90 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e  aOrderBy[]..** ^
33ba0 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
33bb0 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
33bc0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
33bd0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
33be0 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49  *.** The [xBestI
33bf0 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73  ndex] method mus
33c00 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69  t fill aConstrai
33c10 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69  ntUsage[] with i
33c20 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
33c30 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74  out what paramet
33c40 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78  ers to pass to x
33c50 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67  Filter.  ^If arg
33c60 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
33c70 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
33c80 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
33c90 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
33ca0 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
33cb0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
33cc0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
33cd0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
33ce0 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74  gv.  ^(If aConst
33cf0 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
33d00 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
33d10 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
33d20 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
33d30 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
33d40 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
33d50 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
33d60 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
33d70 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a  n by SQLite.)^.*
33d80 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d  *.** ^The idxNum
33d90 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
33da0 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
33db0 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
33dc0 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d  the.** [xFilter]
33dd0 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71   method..** ^[sq
33de0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
33df0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
33e00 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79  xPtr if and only
33e10 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65   if.** needToFre
33e20 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e  eIdxPtr is true.
33e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65  .**.** ^The orde
33e40 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
33e50 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
33e60 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e  om [xFilter]/[xN
33e70 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20  ext] will occur 
33e80 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
33e90 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
33ea0 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
33eb0 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
33ec0 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
33ed0 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
33ee0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
33ef0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
33f00 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
33f10 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
33f20 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
33f30 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
33f40 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
33f50 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
33f60 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
33f70 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
33f80 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
33f90 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
33fa0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
33fb0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
33fc0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
33fd0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
33fe0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
33ff0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
34000 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
34010 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
34020 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
34030 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
34040 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
34050 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
34060 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
34070 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
34080 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
34090 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
340a0 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
340b0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
340c0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
340d0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
340e0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
340f0 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
34100 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
34110 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
34120 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
34130 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
34140 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
34150 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
34160 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
34170 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
34180 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
34190 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
341a0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
341b0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
341c0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
341d0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
341e0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
341f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
34200 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
34210 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
34220 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
34230 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
34240 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
34250 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
34260 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
34270 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
34280 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
34290 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
342a0 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
342b0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
342c0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
342d0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
342e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
342f0 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a    /* Outputs */.
34300 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
34310 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
34320 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e  t_usage {.    in
34330 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20  t argvIndex;    
34340 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c         /* if >0,
34350 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70   constraint is p
34360 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78  art of argv to x
34370 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e  Filter */.    un
34380 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
34390 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
343a0 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
343b0 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
343c0 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
343d0 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
343e0 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
343f0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
34400 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
34410 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
34420 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
34430 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
34440 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
34450 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
34460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
34470 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
34480 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
34490 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
344a0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
344b0 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
344c0 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
344d0 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
344e0 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
344f0 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
34500 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
34510 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
34520 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
34530 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
34540 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ndex */.};../*.*
34550 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
34560 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72  ual Table Constr
34570 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f  aint Operator Co
34580 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
34590 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74  macros defined t
345a0 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  he allowed value
345b0 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  s for the.** [sq
345c0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
345d0 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  ].aConstraint[].
345e0 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20  op field.  Each 
345f0 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73  value represents
34600 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20  .** an operator 
34610 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
34620 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72  a constraint ter
34630 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45 20 63  m in the wHERE c
34640 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75  lause of.** a qu
34650 65 72 79 20 74 68 61 74 20 75 73 65 73 20 61 20  ery that uses a 
34660 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
34670 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
34680 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
34690 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
346a0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
346b0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
346c0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
346d0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
346e0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
346f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
34700 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
34710 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
34720 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34730 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
34740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
34750 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
34760 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
34770 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
34780 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
34790 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   Implementation.
347a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
347b0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
347c0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
347d0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
347e0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
347f0 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d   ^Module names m
34800 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
34810 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
34820 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
34830 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
34840 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
34850 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
34860 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
34870 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
34880 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
34890 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20  .** ^The module 
348a0 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72  name is register
348b0 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ed on the [datab
348c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
348d0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
348e0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
348f0 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20  ter.  ^The name 
34900 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73  of the module is
34910 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a   given by the .*
34920 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
34930 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  er.  ^The third 
34940 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
34950 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
34960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34970 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
34980 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
34990 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20   ^The fourth.** 
349a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
349b0 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74  arbitrary client
349c0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
349d0 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
349e0 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  ough.** into the
349f0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
34a00 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
34a10 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
34a20 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a   table module.**
34a30 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74   when a new virt
34a40 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20  ual table is be 
34a50 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72  being created or
34a60 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a   reinitialized..
34a70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34a80 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
34a90 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
34aa0 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61  has a fifth para
34ab0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
34ac0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
34ad0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
34ae0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e  the pClientData.
34af0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a    ^SQLite will.*
34b00 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  * invoke the des
34b10 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
34b20 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   (if it is not N
34b30 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65  ULL) when SQLite
34b40 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  .** no longer ne
34b50 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44  eds the pClientD
34b60 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ata pointer.  ^T
34b70 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
34b80 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
34b90 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
34ba0 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
34bb0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
34bc0 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
34bd0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
34be0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
34bf0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
34c00 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
34c10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
34c20 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
34c30 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
34c40 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
34c50 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
34c60 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
34c70 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
34c80 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
34c90 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
34ca0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
34cb0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
34cc0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
34cd0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
34ce0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
34cf0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
34d00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34d10 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
34d20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
34d30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
34d40 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
34d50 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
34d60 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
34d70 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34d80 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
34d90 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
34da0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
34db0 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
34dc0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
34dd0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
34de0 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
34df0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
34e00 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
34e10 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
34e20 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
34e30 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
34e40 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
34e50 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
34e60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34e70 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
34e80 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
34e90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
34ea0 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
34eb0 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
34ec0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
34ed0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
34ee0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
34ef0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
34f00 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
34f10 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
34f20 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
34f30 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
34f40 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
34f50 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
34f60 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
34f70 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
34f80 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34f90 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
34fa0 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
34fb0 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
34fc0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
34fd0 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
34fe0 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
34ff0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35000 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
35010 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
35020 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
35030 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
35040 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
35050 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
35060 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
35070 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
35080 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
35090 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
350a0 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
350b0 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
350c0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
350d0 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
350e0 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
350f0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
35100 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
35110 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
35120 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
35130 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
35140 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
35150 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
35160 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
35170 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
35180 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
35190 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
351a0 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
351b0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
351c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
351d0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
351e0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
351f0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
35200 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
35210 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
35220 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
35230 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
35240 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
35250 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
35260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35270 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
35280 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
35290 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
352a0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
352b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
352c0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
352d0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
352e0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
352f0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
35300 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
35310 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
35320 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
35330 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
35340 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
35350 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
35360 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
35370 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
35380 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
35390 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
353a0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
353b0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
353c0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
353d0 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
353e0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
353f0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
35400 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
35410 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
35420 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
35430 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
35440 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
35450 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
35460 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
35470 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
35480 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
35490 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
354a0 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
354b0 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
354c0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
354d0 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
354e0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
354f0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
35500 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
35510 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
35520 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
35530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
35540 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
35550 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
35560 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
35570 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
35580 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
35590 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
355a0 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
355b0 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
355c0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
355d0 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
355e0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
355f0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
35600 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
35610 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
35620 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
35630 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
35640 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
35650 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
35660 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
35670 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
35680 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
35690 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
356a0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
356b0 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
356c0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
356d0 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
356e0 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
356f0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
35700 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
35710 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
35720 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
35730 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
35740 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
35750 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
35760 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
35770 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
35780 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
35790 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
357a0 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
357b0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
357c0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
357d0 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
357e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
357f0 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
35800 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
35810 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
35820 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
35830 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
35840 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
35850 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
35860 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
35870 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
35880 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
35890 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
358a0 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
358b0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
358c0 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
358d0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
358e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
358f0 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
35900 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
35910 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
35920 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
35930 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
35940 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
35950 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
35960 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
35970 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
35980 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
35990 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
359a0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
359b0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
359c0 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
359d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
359e0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
359f0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
35a00 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
35a10 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
35a20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
35a30 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
35a40 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
35a50 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
35a60 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
35a70 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
35a80 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
35a90 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
35aa0 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
35ab0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
35ac0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
35ad0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
35ae0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
35af0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
35b00 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
35b10 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
35b20 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
35b30 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
35b40 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
35b50 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
35b60 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
35b70 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
35b80 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
35b90 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
35ba0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
35bb0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
35bc0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
35bd0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
35be0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
35bf0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
35c00 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
35c10 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
35c20 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
35c30 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
35c40 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
35c50 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
35c60 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
35c70 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
35c80 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
35c90 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
35ca0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
35cb0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
35cc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35cd0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
35ce0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
35cf0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
35d00 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
35d10 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
35d20 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
35d30 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
35d40 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
35d50 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
35d60 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
35d70 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
35d80 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
35d90 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
35da0 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
35db0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
35dc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35dd0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
35de0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
35df0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
35e00 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
35e10 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
35e20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
35e30 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
35e40 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
35e50 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
35e60 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
35e70 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
35e80 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
35e90 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
35ea0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
35eb0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
35ec0 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
35ed0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
35ee0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
35ef0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
35f00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35f10 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
35f20 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
35f30 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
35f40 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
35f50 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
35f60 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
35f70 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
35f80 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
35f90 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
35fa0 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
35fb0 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
35fc0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
35fd0 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
35fe0 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
35ff0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
36000 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
36010 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
36020 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
36030 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
36040 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
36050 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
36060 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
36070 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
36080 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
36090 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
360a0 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
360b0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
360c0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
360d0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
360e0 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
360f0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
36100 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
36110 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
36120 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
36130 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
36140 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
36150 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
36160 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
36170 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
36180 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
36190 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
361a0 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
361b0 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
361c0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
361d0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
361e0 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
361f0 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
36200 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
36210 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
36220 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
36230 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36240 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
36250 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
36260 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
36270 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
36280 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
36290 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
362a0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
362b0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
362c0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
362d0 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
362e0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
362f0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
36300 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
36310 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
36320 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
36330 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
36340 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
36350 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
36360 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
36370 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
36380 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
36390 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
363a0 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
363b0 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
363c0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
363d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
363e0 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
363f0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
36400 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
36410 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
36420 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
36430 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
36440 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
36450 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
36460 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
36470 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
36480 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
36490 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
364a0 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
364b0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
364c0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
364d0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
364e0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
364f0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
36500 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
36510 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
36520 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
36530 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
36540 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
36550 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
36560 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
36570 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
36580 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
36590 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
365a0 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
365b0 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
365c0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
365d0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
365e0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
365f0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
36600 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
36610 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
36620 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
36630 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
36640 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
36650 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36660 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
36670 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
36680 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
36690 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
366a0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
366b0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
366c0 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
366d0 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
366e0 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
366f0 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
36700 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
36710 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
36720 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
36730 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
36740 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
36750 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
36760 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
36770 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
36780 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
36790 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
367a0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
367b0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
367c0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
367d0 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
367e0 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
367f0 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
36800 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
36810 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
36820 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
36830 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
36840 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
36850 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
36860 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
36870 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
36880 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
36890 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
368a0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
368b0 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
368c0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
368d0 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
368e0 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
368f0 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
36900 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
36910 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
36920 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
36930 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
36940 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
36950 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
36960 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
36970 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
36980 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
36990 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
369a0 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
369b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
369c0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
369d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
369e0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
369f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
36a00 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
36a10 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
36a20 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
36a30 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
36a40 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
36a50 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
36a60 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
36a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
36a80 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
36a90 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73  le.**.** ^Closes
36aa0 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
36ab0 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  andle]..**.** ^C
36ac0 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
36ad0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
36ae0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
36af0 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
36b00 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
36b10 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
36b20 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
36b30 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
36b40 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
36b50 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
36b60 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
36b70 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77  e]..** ^If any w
36b80 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20  rites were made 
36b90 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65  to the BLOB, the
36ba0 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20  y might be held 
36bb0 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69  in cache.** unti
36bc0 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72  l the close oper
36bd0 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69  ation if they wi
36be0 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ll fit..**.** ^(
36bf0 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
36c00 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
36c10 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
36c20 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
36c30 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
36c40 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
36c50 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
36c60 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
36c70 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
36c80 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
36c90 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
36ca0 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
36cb0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
36cc0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
36cd0 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a  rn value.)^.**.*
36ce0 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20  * ^(The BLOB is 
36cf0 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
36d00 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
36d10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
36d20 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
36d30 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
36d40 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
36d50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  .)^.**.** ^Calli
36d60 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
36d70 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  with a null poin
36d80 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f 75  ter (such as wou
36d90 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a  ld be returned.*
36da0 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63 61  * by a failed ca
36db0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
36dc0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20  lob_open()]) is 
36dd0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
36de0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36df0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
36e00 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
36e10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36e20 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
36e30 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
36e40 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65  .** ^Returns the
36e50 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
36e60 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73  f the BLOB acces
36e70 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a  sible via the .*
36e80 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  * successfully o
36e90 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pened [BLOB hand
36ea0 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
36eb0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a  argument.  ^The.
36ec0 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62  ** incremental b
36ed0 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73  lob I/O routines
36ee0 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f   can only read o
36ef0 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78  r overwriting ex
36f00 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63  isting.** blob c
36f10 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e  ontent; they can
36f20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73  not change the s
36f30 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a  ize of a blob..*
36f40 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
36f50 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
36f60 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
36f70 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
36f80 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
36f90 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
36fa0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36fb0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
36fc0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
36fd0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
36fe0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
36ff0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
37000 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
37010 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
37020 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
37030 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
37040 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
37050 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
37060 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
37070 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
37080 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
37090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
370a0 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
370b0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
370c0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ly.**.** ^(This 
370d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
370e0 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
370f0 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  om an open [BLOB
37100 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a   handle] into a.
37110 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
37120 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74  ed buffer. N byt
37130 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
37140 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65  opied into buffe
37150 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  r Z.** from the 
37160 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
37170 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
37180 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ffset.)^.**.** ^
37190 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
371a0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
371b0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
371c0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
371d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
371e0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
371f0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
37200 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f  ad.  ^If N or iO
37210 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
37220 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
37230 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
37240 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
37250 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e  ta is read..** ^
37260 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
37270 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
37280 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
37290 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
372a0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
372b0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
372c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
372d0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
372e0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
372f0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
37300 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
37310 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
37320 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
37330 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
37340 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ABORT]..**.** ^(
37350 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
37360 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20  te3_blob_read() 
37370 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
37380 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
37390 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
373a0 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
373b0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
373c0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
373d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
373e0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
373f0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
37400 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
37410 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
37420 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
37430 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
37440 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
37450 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
37460 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
37470 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
37480 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
37490 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
374a0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
374b0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
374c0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
374d0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
374e0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
374f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
37500 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
37510 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ite()]..*/.int s
37520 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
37530 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
37540 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
37550 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
37560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37570 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
37580 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
37590 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ally.**.** ^This
375a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
375b0 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
375c0 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  into an open [BL
375d0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20  OB handle] from 
375e0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
375f0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20  lied buffer. ^N 
37600 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
37610 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
37620 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
37630 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
37640 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
37650 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
37660 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f  .** ^If the [BLO
37670 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
37680 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
37690 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
376a0 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
376b0 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
376c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
376d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
376e0 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
376f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
37700 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
37710 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
37720 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  ^This function m
37730 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
37740 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
37750 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
37760 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
37770 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
37780 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
37790 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
377a0 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
377b0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
377c0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
377d0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
377e0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
377f0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
37800 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
37810 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20  written.  ^If N 
37820 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
37830 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
37840 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
37850 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
37860 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ritten..** The s
37870 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
37880 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d  (and hence the m
37890 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
378a0 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61  N+iOffset).** ca
378b0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
378c0 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
378d0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
378e0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
378f0 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f  * ^An attempt to
37900 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70   write to an exp
37910 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
37920 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
37930 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
37940 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
37950 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68  .  ^Writes to th
37960 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
37970 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
37980 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
37990 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
379a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
379b0 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
379c0 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
379d0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
379e0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
379f0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
37a00 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
37a10 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
37a20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
37a30 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
37a40 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
37a50 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
37a60 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  ts..**.** ^(On s
37a70 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f  uccess, sqlite3_
37a80 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74  blob_write() ret
37a90 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
37aa0 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
37ab0 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f    [error code] o
37ac0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
37ad0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
37ae0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
37af0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
37b00 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
37b10 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
37b20 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
37b30 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
37b40 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
37b50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
37b60 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
37b70 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
37b80 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
37b90 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
37ba0 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
37bb0 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
37bc0 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
37bd0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
37be0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
37bf0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
37c00 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
37c10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
37c20 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
37c30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
37c40 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
37c50 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
37c60 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
37c70 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
37c80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37c90 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65  EF: Virtual File
37ca0 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
37cb0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
37cc0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
37cd0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
37ce0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
37cf0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
37d00 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
37d10 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
37d20 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
37d30 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74  tem.  Most SQLit
37d40 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  e builds come wi
37d50 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
37d60 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
37d70 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
37d80 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
37d90 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
37da0 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
37db0 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
37dc0 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
37dd0 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
37de0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
37df0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
37e00 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  vided..**.** ^Th
37e10 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
37e20 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
37e30 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37e40 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20   to a VFS given 
37e50 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61  its name..** ^Na
37e60 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
37e70 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  sitive..** ^Name
37e80 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
37e90 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
37ea0 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72  ngs..** ^If ther
37eb0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
37ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
37ed0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
37ee0 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
37ef0 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
37f00 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
37f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20  ned..**.** ^New 
37f20 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
37f30 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
37f40 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
37f50 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56  ..** ^Each new V
37f60 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64  FS becomes the d
37f70 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68  efault VFS if th
37f80 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
37f90 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  is set..** ^The 
37fa0 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
37fb0 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
37fc0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
37fd0 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f  t injury..** ^To
37fe0 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
37ff0 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
38000 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
38010 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
38020 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
38030 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
38040 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
38050 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
38060 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
38070 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
38080 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
38090 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
380a0 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
380b0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
380c0 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
380d0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
380e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
380f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
38100 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74  .**.** ^Unregist
38110 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
38120 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
38130 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
38140 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68  face..** ^(If th
38150 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
38160 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
38170 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
38180 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
38190 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
381a0 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
381b0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
381c0 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  .)^.*/.sqlite3_v
381d0 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f  fs *sqlite3_vfs_
381e0 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20  find(const char 
381f0 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20  *zVfsName);.int 
38200 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
38210 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
38220 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29  *, int makeDflt)
38230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
38240 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c  s_unregister(sql
38250 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a  ite3_vfs*);../*.
38260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
38270 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  exes.**.** The S
38280 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
38290 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  these routines f
382a0 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e  or thread.** syn
382b0 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68  chronization. Th
382c0 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
382d0 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
382e0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
382f0 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
38300 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
38310 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
38320 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
38330 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
38340 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
38350 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
38360 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
38370 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38380 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75  s.** of these mu
38390 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
383a0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
383b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
383c0 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
383d0 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
383e0 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68  pile-time.  ^(Th
383f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69  e following.** i
38400 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61  mplementations a
38410 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  re available in 
38420 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a  the SQLite core:
38430 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
38440 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
38450 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_OS2.** <li>  
38460 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
38470 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20  HREAD.** <li>   
38480 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
38490 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
384a0 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
384b0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  </ul>)^.**.** ^T
384c0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
384d0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
384e0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
384f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
38500 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
38510 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
38520 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
38530 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
38540 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
38550 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49  tion.  ^The SQLI
38560 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
38570 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
38580 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
38590 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
385a0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
385b0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
385c0 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
385d0 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
385e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  s..**.** ^(If SQ
385f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
38600 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
38610 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72  _MUTEX_APPDEF pr
38620 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61  eprocessor.** ma
38630 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74  cro defined (wit
38640 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45  h "-DSQLITE_MUTE
38650 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68  X_APPDEF=1"), th
38660 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69  en no mutex.** i
38670 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
38680 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74   included with t
38690 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74  he library. In t
386a0 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  his case the.** 
386b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
386c0 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d   supply a custom
386d0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
386e0 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a  ation using the.
386f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
38700 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20  G_MUTEX] option 
38710 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
38720 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e  onfig() function
38730 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  .** before calli
38740 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ng sqlite3_initi
38750 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f  alize() or any o
38760 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69  ther public sqli
38770 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  te3_.** function
38780 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69   that calls sqli
38790 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
387a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
387b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
387c0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c  oc() routine all
387d0 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20  ocates a new.** 
387e0 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e  mutex and return
387f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
38800 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e  t. ^If it return
38810 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
38820 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
38830 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
38840 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69  llocated.  ^SQLi
38850 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
38860 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
38870 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
38880 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
38890 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  .** to sqlite3_m
388a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20  utex_alloc() is 
388b0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
388c0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a  eger constants:.
388d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
388e0 69 3e 2